@esuyo/esuyo-opencode-tks 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8perezm
+
+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/NOTICE

@@ -0,0 +1,17 @@
+esuyo-opencode-tks
+==================
+
+This project is a fork of and is derived from:
+
+  Tarquinen/oc-tps
+  https://github.com/Tarquinen/oc-tps
+  commit 89bf5b87f933ee593e85e8458ee79195a9f59a75 (version 0.0.10)
+
+The upstream project did not declare a license at the time this fork was
+created. The original source is included here with full attribution and is
+used under the assumption of an MIT-compatible license; the original author
+retains all rights to their work. If upstream adds or changes its license,
+the attribution and license terms of this fork will be updated accordingly.
+
+New code and modifications in this fork are released under the MIT License
+(see LICENSE).

package/README.md

@@ -0,0 +1,119 @@
+# esuyo-opencode-tks
+
+Displays live TPS (tokens per second), average TPS, average TTFT (time to first
+token), and **GAP** (time between the end of the previous assistant response and
+the start of the next one) in the OpenCode session prompt. Optionally appends
+per-message stats as JSONL for later analysis.
+
+```
+TPS 62.4 | AVG 58.1 | TTFT 0.9s | GAP 12.3s
+```
+
+![Demo](./assets/demo.gif)
+
+## Installation
+
+Install from the CLI:
+
+```bash
+opencode plugin @esuyo/esuyo-opencode-tks@latest --global
+```
+
+Requires `opencode` `1.3.14` or newer.
+
+If you previously installed the upstream `oc-tps`, uninstall it first so both
+plugins do not register the same slot:
+
+```bash
+opencode plugin oc-tps --global --uninstall
+```
+
+## Metrics
+
+| Metric | Meaning |
+| --- | --- |
+| `TPS` | Live tokens/sec over the last 5s streaming window. |
+| `AVG` | Session-average tokens/sec across completed assistant messages. |
+| `TTFT` | Session-average time from request start to first token. |
+| `GAP` | Time between the previous final assistant completion and this message's start, including user think-time. Shows `-` for the first message. |
+
+GAP is measured between **final** completions only; intermediate
+`finish: "tool-calls"` chunks do not reset the baseline.
+
+## File logging
+
+Every completed assistant message is appended as one JSON object per line
+(JSONL). No prompt or response text is ever written — numeric metadata only.
+
+Default path:
+
+```
+~/.local/share/opencode/esuyo-opencode-tks.log
+```
+
+Override with an environment variable:
+
+```bash
+export ESUYO_TPS_LOG=/path/to/tps.log
+```
+
+Disable logging by pointing it at `/dev/null`:
+
+```bash
+export ESUYO_TPS_LOG=/dev/null
+```
+
+### Schema (v1)
+
+```jsonc
+{
+  "v": 1,
+  "at": "2026-09-11T23:50:00.000Z",   // completion wall-time
+  "sessionID": "ses_...",
+  "messageID": "msg_...",
+  "finish": "stop",                    // "stop" | "tool-calls" | ...
+  "tokensOutput": 123,
+  "tokensReasoning": 45,
+  "tokensTotal": 168,
+  "durationMs": 2345,                  // first response -> end
+  "ttftMs": 456,                       // request start -> first response
+  "gapMs": 12340,                      // previous completion -> this start (null on first)
+  "avgTps": 71.6,
+  "liveSamplesDropped": false
+}
+```
+
+Log writing is best-effort: I/O errors are swallowed so the TUI never crashes.
+
+### Rotation
+
+v1 does not rotate the log. Use `logrotate`, for example:
+
+```
+/root/.local/share/opencode/esuyo-opencode-tks.log {
+    weekly
+    rotate 4
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+Credits & license
+-----------------
+
+Forked from [`Tarquinen/oc-tps`](https://github.com/Tarquinen/oc-tps) at commit
+`89bf5b8` (v0.0.10). The upstream project declared no license; original work
+remains attributed to its author. See [NOTICE](./NOTICE) and [LICENSE](./LICENSE)
+(MIT).
+
+---

package/package.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@esuyo/esuyo-opencode-tks",
+  "version": "0.1.2",
+  "description": "Live TPS, average TPS, average TTFT, and response GAP metrics for OpenCode sessions, with optional JSONL stats logging.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/8perezm/esuyo-opencode-tks"
+  },
+  "author": "8perezm (https://github.com/8perezm)",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./tui": {
+      "import": "./tui.tsx"
+    }
+  },
+  "engines": {
+    "opencode": ">=1.3.14"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build:test": "tsc -p tsconfig.test.json",
+    "pretest": "npm run build:test",
+    "test": "node test/logging.test.mjs"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.4.5",
+    "@opentui/solid": "^0.4.5",
+    "solid-js": "^1.9.12"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": ">=1.4.3",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "assets/",
+    "README.md",
+    "NOTICE",
+    "LICENSE",
+    "tui.tsx"
+  ]
+}

package/tui.tsx

@@ -0,0 +1,363 @@
+/** @jsxImportSource @opentui/solid */
+import type { TextRenderable } from "@opentui/core"
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { appendFile, mkdir } from "node:fs/promises"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { onCleanup } from "solid-js"
+
+type StreamSample = {
+  at: number
+  tokens: number
+}
+
+const STREAM_WINDOW_MS = 5_000
+const LIVE_STALE_MS = 1_500
+const SINGLE_SAMPLE_MS = 1_000
+type MessageTiming = {
+  sessionID: string
+  requestStartAt: number
+  firstResponseAt?: number
+  firstTokenAt?: number
+  lastTokenAt?: number
+  lastToolCallAt?: number
+}
+
+type SessionAverage = {
+  totalTokens: number
+  totalDurationMs: number
+  totalTtftMs: number
+  messageCount: number
+}
+
+type TrackerState = {
+  streamSamplesBySession: Record<string, StreamSample[]>
+  messageTimingByID: Record<string, MessageTiming>
+  sessionAverageByID: Record<string, SessionAverage>
+  lastCompletedAtBySession: Record<string, number>
+  lastGapMsBySession: Record<string, number>
+  liveSamplesDroppedBySession: Record<string, boolean>
+}
+
+type TrackerListener = () => void
+
+const LOG_PATH =
+  process.env.ESUYO_TPS_LOG ?? join(homedir(), ".local/share/opencode", "esuyo-opencode-tks.log")
+
+async function logLine(obj: unknown) {
+  try {
+    await appendFile(LOG_PATH, JSON.stringify(obj) + "\n", "utf8")
+  } catch {}
+}
+
+function estimateStreamTokens(delta: string) {
+  return Math.max(1, Math.ceil(Buffer.byteLength(delta, "utf8") / 5))
+}
+
+function formatRate(value: number) {
+  if (!Number.isFinite(value) || value <= 0) return undefined
+  if (value >= 100) return `${Math.round(value)}`
+  if (value >= 10) return `${value.toFixed(1)}`
+  return `${value.toFixed(2)}`
+}
+
+function formatTtft(value: number) {
+  if (!Number.isFinite(value) || value < 0) return undefined
+  return `${value.toFixed(1)}s`
+}
+
+function activeDurationMs(samples: StreamSample[], tailAt?: number) {
+  if (samples.length === 0) return 0
+  if (samples.length === 1) {
+    const tailDuration = tailAt ? Math.max(0, tailAt - samples[0].at) : SINGLE_SAMPLE_MS
+    return Math.min(Math.max(tailDuration, 250), SINGLE_SAMPLE_MS)
+  }
+
+  let duration = 0
+  for (let i = 1; i < samples.length; i++) {
+    duration += Math.max(0, samples[i].at - samples[i - 1].at)
+  }
+
+  if (tailAt) {
+    duration += Math.max(0, tailAt - samples[samples.length - 1].at)
+  }
+
+  return Math.max(duration, SINGLE_SAMPLE_MS)
+}
+
+function SessionPromptRight(props: {
+  api: Parameters<TuiPlugin>[0]
+  sessionID: string
+  tracker: TrackerState
+  subscribe: (listener: TrackerListener) => () => void
+}) {
+  let text: TextRenderable | undefined
+
+  const sync = () => {
+    if (!text) return
+    text.content = statusText()
+    props.api.renderer.requestRender()
+  }
+
+  const unsubscribe = props.subscribe(sync)
+  onCleanup(unsubscribe)
+
+  return (
+    <text
+      ref={(ref: TextRenderable) => {
+        text = ref
+        sync()
+      }}
+      fg={props.api.theme.current.textMuted}
+    >
+      {statusText()}
+    </text>
+  )
+
+  function sessionAverage() {
+    const totals = props.tracker.sessionAverageByID[props.sessionID]
+    if (!totals || totals.totalTokens <= 0 || totals.totalDurationMs <= 0) return undefined
+    return formatRate(totals.totalTokens / (totals.totalDurationMs / 1000))
+  }
+
+  function sessionTtft() {
+    const totals = props.tracker.sessionAverageByID[props.sessionID]
+    if (!totals || totals.messageCount <= 0 || totals.totalTtftMs < 0) return undefined
+    return formatTtft(totals.totalTtftMs / totals.messageCount / 1000)
+  }
+
+  function liveTps() {
+    const status = props.api.state.session.status(props.sessionID)
+    if (status?.type === "idle") return undefined
+    const samples = props.tracker.streamSamplesBySession[props.sessionID] ?? []
+    if (samples.length === 0) return undefined
+    const now = Date.now()
+    const relevant = samples.filter((sample) => now - sample.at <= STREAM_WINDOW_MS)
+    if (relevant.length === 0) return undefined
+    const lastSample = relevant[relevant.length - 1]
+    if (!lastSample || now - lastSample.at > LIVE_STALE_MS) return undefined
+    const total = relevant.reduce((sum, sample) => sum + sample.tokens, 0)
+    const durationSeconds = activeDurationMs(relevant, now) / 1000
+    if (durationSeconds <= 0) return undefined
+    return formatRate(total / durationSeconds)
+  }
+
+  function lastGap() {
+    const ms = props.tracker.lastGapMsBySession[props.sessionID]
+    if (typeof ms !== "number" || ms < 0) return undefined
+    return ms >= 10000 ? `${(ms / 1000).toFixed(0)}s` : `${(ms / 1000).toFixed(1)}s`
+  }
+
+  function statusText() {
+    const live = liveTps() ?? "-"
+    const avg = sessionAverage() ?? "-"
+    const ttft = sessionTtft() ?? "-"
+    const gap = lastGap() ?? "-"
+    return `TPS ${live} | AVG ${avg} | TTFT ${ttft} | GAP ${gap}`
+  }
+}
+
+const tui: TuiPlugin = async (api) => {
+  const tracker: TrackerState = {
+    streamSamplesBySession: {},
+    messageTimingByID: {},
+    sessionAverageByID: {},
+    lastCompletedAtBySession: {},
+    lastGapMsBySession: {},
+    liveSamplesDroppedBySession: {},
+  }
+  const listeners = new Set<TrackerListener>()
+
+  try {
+    await mkdir(dirname(LOG_PATH), { recursive: true })
+  } catch {}
+
+  const bump = () => {
+    for (const listener of listeners) listener()
+  }
+
+  const pruneSamples = (now = Date.now()) => {
+    let changed = false
+
+    for (const [sessionID, samples] of Object.entries(tracker.streamSamplesBySession)) {
+      const next = samples.filter((sample) => now - sample.at <= STREAM_WINDOW_MS)
+      if (next.length !== samples.length) {
+        changed = true
+        if (next.length > 0) tracker.streamSamplesBySession[sessionID] = next
+        else delete tracker.streamSamplesBySession[sessionID]
+      }
+    }
+
+    if (changed) bump()
+  }
+
+  const clearLiveSamples = (sessionID: string) => {
+    if (!tracker.streamSamplesBySession[sessionID]?.length) return
+    delete tracker.streamSamplesBySession[sessionID]
+    tracker.liveSamplesDroppedBySession[sessionID] = true
+    bump()
+  }
+
+  const appendSample = (sessionID: string, messageID: string, sample: StreamSample) => {
+    const now = sample.at
+    tracker.streamSamplesBySession[sessionID] = [
+      ...(tracker.streamSamplesBySession[sessionID] ?? []).filter((item) => now - item.at <= STREAM_WINDOW_MS),
+      sample,
+    ]
+    const timing = tracker.messageTimingByID[messageID]
+    if (timing) {
+      tracker.messageTimingByID[messageID] = timing.firstTokenAt
+        ? { ...timing, lastTokenAt: now }
+        : {
+            ...timing,
+            firstResponseAt: timing.firstResponseAt ?? now,
+            firstTokenAt: now,
+            lastTokenAt: now,
+          }
+    }
+    bump()
+  }
+
+  const onDelta = api.event.on("message.part.delta", (evt) => {
+    if (evt.properties.field !== "text") return
+    const parts = api.state.part(evt.properties.messageID)
+    const part = parts.find((item) => item.id === evt.properties.partID)
+    if (!part) return
+    if (part.type !== "text" && part.type !== "reasoning") return
+    appendSample(evt.properties.sessionID, evt.properties.messageID, {
+      at: Date.now(),
+      tokens: estimateStreamTokens(evt.properties.delta),
+    })
+  })
+
+  const onMessage = api.event.on("message.updated", (evt) => {
+    if (evt.properties.info.role !== "assistant") return
+    const sessionID = evt.properties.info.sessionID ?? evt.properties.sessionID
+
+    if (!evt.properties.info.time.completed) {
+      const existing = tracker.messageTimingByID[evt.properties.info.id]
+      if (!existing) tracker.liveSamplesDroppedBySession[sessionID] = false
+      const prev = tracker.lastCompletedAtBySession[sessionID]
+      if (typeof prev === "number") {
+        tracker.lastGapMsBySession[sessionID] = Math.max(evt.properties.info.time.created - prev, 0)
+      }
+      tracker.messageTimingByID[evt.properties.info.id] = {
+        sessionID,
+        requestStartAt: evt.properties.info.time.created,
+        firstResponseAt: existing?.firstResponseAt,
+        firstTokenAt: existing?.firstTokenAt,
+        lastTokenAt: existing?.lastTokenAt,
+        lastToolCallAt: existing?.lastToolCallAt,
+      }
+      bump()
+      return
+    }
+
+    const timing = tracker.messageTimingByID[evt.properties.info.id]
+    if (timing?.sessionID === sessionID && typeof timing.firstResponseAt === "number") {
+      const totalTokens = evt.properties.info.tokens.output + evt.properties.info.tokens.reasoning
+      const endAt =
+        evt.properties.info.finish === "tool-calls"
+          ? timing.lastToolCallAt
+          : evt.properties.info.time.completed
+      const durationMs = typeof endAt === "number" ? Math.max(endAt - timing.firstResponseAt, 1) : undefined
+      const ttftMs = Math.max(timing.firstResponseAt - timing.requestStartAt, 0)
+      if (totalTokens > 0 && durationMs) {
+        const totals = tracker.sessionAverageByID[sessionID] ?? {
+          totalTokens: 0,
+          totalDurationMs: 0,
+          totalTtftMs: 0,
+          messageCount: 0,
+        }
+        tracker.sessionAverageByID[sessionID] = {
+          totalTokens: totals.totalTokens + totalTokens,
+          totalDurationMs: totals.totalDurationMs + durationMs,
+          totalTtftMs: totals.totalTtftMs + ttftMs,
+          messageCount: totals.messageCount + 1,
+        }
+        void logLine({
+          v: 1,
+          at: new Date(evt.properties.info.time.completed).toISOString(),
+          sessionID,
+          messageID: evt.properties.info.id,
+          finish: evt.properties.info.finish,
+          tokensOutput: evt.properties.info.tokens.output,
+          tokensReasoning: evt.properties.info.tokens.reasoning,
+          tokensTotal: totalTokens,
+          durationMs,
+          ttftMs,
+          gapMs: tracker.lastGapMsBySession[sessionID] ?? null,
+          avgTps: Number((totalTokens / (durationMs / 1000)).toFixed(2)),
+          liveSamplesDropped: tracker.liveSamplesDroppedBySession[sessionID] ?? false,
+        })
+      }
+    }
+    if (evt.properties.info.finish !== "tool-calls") {
+      tracker.lastCompletedAtBySession[sessionID] = evt.properties.info.time.completed
+    }
+    delete tracker.messageTimingByID[evt.properties.info.id]
+    delete tracker.liveSamplesDroppedBySession[sessionID]
+    pruneSamples(evt.properties.info.time.completed)
+    bump()
+  })
+
+  const onPart = api.event.on("message.part.updated", (evt) => {
+    if (evt.properties.part.type !== "tool") return
+    const sessionID = evt.properties.part.sessionID ?? evt.properties.sessionID
+    if (
+      evt.properties.part.state.status === "running" ||
+      evt.properties.part.state.status === "completed" ||
+      evt.properties.part.state.status === "error"
+    ) {
+      clearLiveSamples(sessionID)
+    }
+    const timing = tracker.messageTimingByID[evt.properties.part.messageID]
+    if (!timing) return
+    if (evt.properties.part.state.status === "pending") {
+      tracker.messageTimingByID[evt.properties.part.messageID] = {
+        ...timing,
+        firstResponseAt: timing.firstResponseAt ?? evt.properties.time,
+      }
+      bump()
+      return
+    }
+    if (evt.properties.part.state.status !== "running") return
+    tracker.messageTimingByID[evt.properties.part.messageID] = {
+      ...timing,
+      lastToolCallAt: evt.properties.part.state.time.start,
+    }
+    bump()
+  })
+
+  const timer = setInterval(() => {
+    pruneSamples()
+    bump()
+  }, 1000)
+
+  api.lifecycle.onDispose(() => {
+    onDelta()
+    onMessage()
+    onPart()
+    clearInterval(timer)
+  })
+
+  api.slots.register({
+    slots: {
+      session_prompt_right(_ctx, value) {
+        return <SessionPromptRight api={api} sessionID={value.session_id} tracker={tracker} subscribe={(listener) => {
+          listeners.add(listener)
+          return () => {
+            listeners.delete(listener)
+          }
+        }} />
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "esuyo-opencode-tks",
+  tui,
+}
+
+export default plugin