opencode2-tps 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 P-Theo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# opencode2-tps
+
+Live token-throughput indicator for the OpenCode 2 TUI prompt composer.
+
+While a session streams, the top right of the composer shows the estimated tokens and the throughput of the current run:
+
+```text
+1712 tok · 51.5 t/s
+```
+
+When the run ends, the number freezes at the run average and stays there until the next run starts. Nothing is shown on the home screen, or before the first token of a run.
+
+## Install
+
+Built against the OpenCode 2 preview and tested on `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.
+
+Add the package to `~/.config/opencode/cli.json`:
+
+```json
+{
+  "plugins": ["opencode2-tps"]
+}
+```
+
+To set options, use the object form:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "opencode2-tps",
+      "options": { "display": "tps", "refreshHz": 12 }
+    }
+  ]
+}
+```
+
+A running TUI picks up `cli.json` changes immediately. On first use it installs the package into its own cache, `~/.cache/opencode/packages/opencode2-tps/` on Linux.
+
+That cache is keyed on the entry text and is never refreshed once it exists, so a restart alone will not pick up a new release. To upgrade, delete the directory and restart:
+
+```sh
+rm -rf ~/.cache/opencode/packages/opencode2-tps
+```
+
+To pin a version instead, put the range in the entry — `"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:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "opencode2-tps",
+      "options": { "display": "tps", "refreshHz": 12 }
+    },
+    "-opencode2.tps"
+  ]
+}
+```
+
+## Configuration
+
+The defaults are usable as they are. For the full option list, the ranges and more examples, see [Configuration](docs/configuration.md).
+
+## 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 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.
+
+For more detail, see [Architecture](docs/development.md#architecture).
+
+## Sub-agents
+
+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.
+
+## Development
+
+To work on the plugin, see [Development](docs/development.md). To publish a new version, see [Release](docs/release.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/tui.js

@@ -0,0 +1,456 @@
+import { effect as _$effect } from "@opentui/solid";
+import { insertNode as _$insertNode } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+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 {
+    appendFileSync(debugState.file, `${new Date().toISOString()} ${line}\n`);
+  } catch {
+    // debug only; never break the host
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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
+};
+// The frozen final average stays visible until the next prompt starts a new run.
+
+function estimateTokens(bytes) {
+  return Math.ceil(bytes / BYTES_PER_TOKEN);
+}
+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",
+        samples: [],
+        bytes: 0,
+        activeMs: 0,
+        lastSampleAt: null,
+        frozen: null
+      };
+      this.runs.set(sessionID, st);
+    }
+    return st;
+  }
+  beginRun(sessionID) {
+    const st = this.state(sessionID);
+    st.phase = "running";
+    st.samples = [];
+    st.bytes = 0;
+    st.activeMs = 0;
+    st.lastSampleAt = null;
+    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.runs.delete(sessionID);
+    }
+  }
+  push(sessionID, delta, now) {
+    if (!delta) return;
+    const st = this.state(sessionID);
+    if (st.phase !== "running") this.beginRun(sessionID); // execution.started missed
+    st.frozen = null;
+    // 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;
+  }
+  finish(sessionID, now) {
+    const st = this.runs.get(sessionID);
+    if (!st || st.phase === "ended") return;
+    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);
+    if (tokens <= 0) {
+      this.runs.delete(sessionID);
+      return;
+    }
+    const seconds = Math.max(st.activeMs, this.config.singleSampleMinMs) / 1000;
+    st.frozen = {
+      tps: tokens / seconds,
+      tokens
+    };
+    st.samples = [];
+    mark(`finish sid=${sessionID} tokens=${tokens} activeMs=${st.activeMs} tps=${st.frozen.tps.toFixed(1)}`);
+  }
+  evict(sessionID) {
+    this.runs.delete(sessionID);
+  }
+  hasRunning() {
+    for (const st of this.runs.values()) if (st.phase === "running") return true;
+    return false;
+  }
+
+  // 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);
+    }
+    return tokens / durationMs * 1000;
+  }
+  value(sessionID, now) {
+    const st = this.runs.get(sessionID);
+    if (!st) return null;
+    if (st.frozen) return {
+      tps: st.frozen.tps,
+      tokens: st.frozen.tokens,
+      frozen: true
+    };
+    if (st.phase !== "running") return null;
+    const tokens = estimateTokens(st.bytes);
+    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;
+    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);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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) {
+  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),
+    debug: raw.debug === true
+  };
+}
+export function formatLabel(value, display) {
+  if (display === "tokens") return `${value.tokens} tok`;
+  if (display === "tps") return `${formatTps(value.tps)} t/s`;
+  return `${value.tokens} tok · ${formatTps(value.tps)} t/s`;
+}
+
+// ---------------------------------------------------------------------------
+// plugin
+
+// Event payloads are taken from the SDK's own union (via the non-generic
+// `data.listen` signature) rather than restated structurally: handlers are
+// contravariant, so hand-written shapes keep typechecking after a field rename.
+
+const definition = {
+  id: "opencode2.tps",
+  setup(ctx) {
+    // Generation guard: the host may start a new generation of this plugin
+    // without disposing the previous one (observed on server (re)attach), and
+    // hot reload shares `storage.memory` across generations. Only the newest
+    // generation may count tokens or render.
+    const [gen, setGen] = ctx.storage.memory("generation", {
+      initial: {
+        active: 0
+      }
+    });
+    const mine = gen.active + 1;
+    setGen(d => {
+      d.active = mine;
+    });
+    const isActive = () => gen.active === mine;
+    const options = resolveOptions(ctx.options);
+    configureDebug(options.debug || isEnvEnabled(process.env["TPS_DEBUG"]));
+    const tracker = new TpsTracker(options);
+    const [version, setVersion] = createSignal(0);
+    mark(`setup ok app=${ctx.app.version} gen=${mine} display=${options.display} refreshHz=${options.refreshHz}`);
+
+    // Rendering is throttled: deltas arrive at 100-200/s, and every bump costs
+    // a memo recompute plus a terminal repaint to move a number no one can read
+    // faster than ~10 Hz. Handlers only set a flag; the timer does the work,
+    // and it only runs while a session is actually streaming.
+    let dirty = false;
+    let timer;
+    const flush = () => {
+      // A superseded generation stops ticking even if its cleanup never ran.
+      if (!isActive()) {
+        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.
+      if (dirty || running) {
+        dirty = false;
+        setVersion(v => v + 1);
+      }
+      if (!running) stopTimer();
+    };
+    function stopTimer() {
+      if (timer === undefined) return;
+      clearInterval(timer);
+      timer = undefined;
+    }
+    const touch = () => {
+      dirty = true;
+      if (timer !== undefined) return;
+      timer = setInterval(flush, Math.round(1000 / options.refreshHz));
+      timer.unref?.();
+    };
+    const onDelta = e => {
+      if (!isActive()) return;
+      tracker.push(e.data.sessionID, e.data.delta, Date.now());
+      touch();
+    };
+    const onFinish = e => {
+      if (!isActive()) return;
+      tracker.finish(e.data.sessionID, Date.now());
+      touch();
+    };
+    const unsubs = [ctx.data.on("session.execution.started", e => {
+      if (!isActive()) return;
+      tracker.beginRun(e.data.sessionID);
+      touch();
+    }), 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 => {
+      if (!isActive()) return;
+      tracker.evict(e.data.sessionID);
+      touch();
+    })];
+    const unslot = ctx.ui.slot({
+      append: "session.composer.top",
+      render: input => {
+        const label = createMemo(() => {
+          version();
+          if (!isActive()) return null;
+          const v = tracker.value(input.sessionID, Date.now());
+          if (!v) return null;
+          return formatLabel(v, options.display);
+        });
+        return _$createComponent(Show, {
+          get when() {
+            return label();
+          },
+          children: text => (() => {
+            var _el$ = _$createElement("box"),
+              _el$2 = _$createElement("text");
+            _$insertNode(_el$, _el$2);
+            _$setProp(_el$, "width", "100%");
+            _$setProp(_el$, "flexDirection", "row");
+            _$setProp(_el$, "justifyContent", "flex-end");
+            _$insert(_el$2, () => `${text()} `);
+            _$effect(_$p => _$setProp(_el$2, "fg", ctx.theme.text.subdued, _$p));
+            return _el$;
+          })()
+        });
+      }
+    });
+    return () => {
+      for (const unsub of unsubs) unsub();
+      unslot();
+      stopTimer();
+      if (gen.active === mine) setGen(d => {
+        d.active = 0;
+      });
+      mark(`cleanup ok gen=${mine}`);
+    };
+  }
+};
+export default definition;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "opencode2-tps",
+  "version": "0.1.0-rc.1",
+  "description": "Live token-throughput indicator for the OpenCode 2 TUI prompt composer",
+  "license": "MIT",
+  "author": "P-Theo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/P-Theo/opencode2-tps.git"
+  },
+  "homepage": "https://github.com/P-Theo/opencode2-tps#readme",
+  "bugs": "https://github.com/P-Theo/opencode2-tps/issues",
+  "type": "module",
+  "keywords": [
+    "opencode",
+    "opencode2",
+    "tui",
+    "plugin",
+    "tps",
+    "tokens",
+    "throughput"
+  ],
+  "exports": {
+    ".": "./dist/tui.js",
+    "./tui": "./dist/tui.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@opentui/solid": ">=0.5.3",
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/solid": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    }
+  },
+  "overrides": {
+    "@opentui/solid": {
+      "@babel/core": "^7.29.7"
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@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",
+    "@oxlint/plugins": "^1.78.0",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^24.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",
+    "check": "tsc --noEmit",
+    "lint": "oxlint",
+    "test": "bun test",
+    "prepack": "npm run lint && npm run check && npm test && npm run build"
+  }
+}