@foae/opencode-timings 0.1.2 → 0.2.1

package/README.md

@@ -9,6 +9,8 @@ Files panels, reading the session's messages directly from the TUI's reactive
 state. Nothing is ever injected into the message stream, so there is **zero
 context-window pollution**.
 
+![The Timing panel in OpenCode's sidebar — api/wall 34%, api 19s · wall 56s, turns 5 · avg 4s, slowest 6s — sitting between the built-in Quota and LSP sections](https://raw.githubusercontent.com/foae/opencode-timings/main/opencode-timings-screenshot.png)
+
 ```
 Timing
 api/wall ██████░░ 78%
@@ -61,7 +63,7 @@ Pass options using the tuple form (`[spec, options]`) in `tui.json`:
   "plugin": [
     ["@foae/opencode-timings@latest", {
       "mode": "fancy",
-      "fields": { "api": true, "wall": true, "turns": true, "avg": true, "slow": true, "sparkline": true }
+      "fields": { "ratio": true, "api": true, "wall": true, "turns": true, "avg": true, "slow": true, "sparkline": true }
     }]
   ]
 }
@@ -69,8 +71,8 @@ Pass options using the tuple form (`[spec, options]`) in `tui.json`:
 
 | Option   | Values | Default | Meaning |
 |----------|--------|---------|---------|
-| `mode`   | `"fancy"` \| `"simple"` | `"fancy"` | `fancy` draws a bar gauge for the API/wall ratio and a sparkline of recent turn durations; `simple` is plain labeled rows. |
-| `fields` | object of booleans | all `true` | Toggle individual values: `api`, `wall`, `turns`, `avg`, `slow`, `sparkline` (`sparkline` is fancy-only). |
+| `mode`   | `"fancy"` \| `"simple"` | `"fancy"` | `fancy` draws the gauge bar on the `api/wall` row and adds the per-turn sparkline; `simple` is the same rows without the bar or sparkline. |
+| `fields` | object of booleans | all `true` | Each toggles exactly one value: `ratio` (the `api/wall` gauge + percent), `api`, `wall`, `turns`, `avg`, `slow`, `sparkline` (`sparkline` is fancy-only). Values that share a line drop out individually. |
 
 With no options (a plain `"@foae/opencode-timings@latest"` string), it defaults to `fancy` mode with all fields shown.
 
@@ -78,6 +80,21 @@ With no options (a plain `"@foae/opencode-timings@latest"` string), it defaults
 
 - OpenCode `1.15.x` or newer (uses the TUI slot plugin API).
 
+## Development
+
+Built and run with [Bun](https://bun.sh). The package ships raw source — there is no build step; OpenCode loads `src/tui.tsx` directly.
+
+- `src/timing.ts` — pure timing math, formatting, and config parsing (no JSX), unit-tested.
+- `src/tui.tsx` — the SolidJS sidebar component and the slot registration.
+
+```sh
+bun install
+bun run typecheck   # tsc --noEmit
+bun test            # unit tests for the pure logic in src/timing.ts
+```
+
+`opentui`, `solid-js`, and the OpenCode plugin/SDK are **peer dependencies** — at runtime they come from the OpenCode host so the plugin shares its renderer; the `devDependencies` mirror them for local typecheck and tests.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foae/opencode-timings",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "OpenCode TUI sidebar panel showing per-session timing: total API/inference time, wall-clock, turns, average and slowest turn. Zero context-window pollution.",
   "license": "MIT",
   "author": "foae",
@@ -39,21 +39,28 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "typecheck": "tsc --noEmit"
+  "engines": {
+    "bun": ">=1.0.0"
   },
-  "dependencies": {
-    "@opentui/core": "^0.1.107",
-    "@opentui/solid": "^0.1.107",
-    "solid-js": "^1.9.12"
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun run test"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.14.29"
+    "@opencode-ai/plugin": "^1.15.0",
+    "@opentui/core": ">=0.2.16",
+    "@opentui/solid": ">=0.2.16",
+    "solid-js": "^1.9.12"
   },
   "devDependencies": {
-    "@opencode-ai/plugin": "^1.14.29",
-    "@opencode-ai/sdk": "^1.14.29",
+    "@opencode-ai/plugin": "^1.15.0",
+    "@opencode-ai/sdk": "^1.15.0",
+    "@opentui/core": "^0.3.1",
+    "@opentui/solid": "^0.3.1",
+    "@types/bun": "^1.1.0",
     "@types/node": "^22.0.0",
+    "solid-js": "1.9.12",
     "typescript": "^5.8.0"
   }
 }

package/src/timing.ts

@@ -0,0 +1,183 @@
+/**
+ * Pure timing computation, formatting, and config parsing for the
+ * opencode-timings panel — deliberately free of JSX and any opentui/solid
+ * import so it loads under a plain TypeScript runtime (e.g. `bun test`) without
+ * OpenCode's Solid JSX preload. The rendering lives in `tui.tsx`.
+ *
+ * Metrics (per session):
+ *   - api      total assistant inference time = sum of (time.completed - time.created)
+ *              over every completed assistant message.
+ *   - wall     span from the first to the last message timestamp (includes the time
+ *              you spend reading/typing between turns), so api is a fraction of it.
+ *   - apiPct   api's share of wall-clock, clamped to 0–100 for the gauge/percent.
+ *   - turns    number of completed assistant messages, plus the average duration.
+ *   - slowest  the single slowest assistant message.
+ *   - durations per-turn durations, fed to the sparkline.
+ */
+import type { Message } from "@opencode-ai/sdk/v2"
+
+// Narrower than the simple-mode rows so the "api/wall" label + gauge + percent
+// fit one sidebar line without wrapping.
+export const BAR_WIDTH = 8
+export const SPARK_POINTS = 12
+export const SPARK_LEVELS = "▁▂▃▄▅▆▇█"
+
+export type Mode = "fancy" | "simple"
+// Each field toggles exactly one displayed value. `ratio` is the api/wall gauge
+// (the panel's headline metric); `sparkline` is fancy-only. Order matches the
+// top-to-bottom render order.
+export type Fields = {
+  ratio: boolean
+  api: boolean
+  wall: boolean
+  turns: boolean
+  avg: boolean
+  slow: boolean
+  sparkline: boolean
+}
+export const DEFAULT_FIELDS: Fields = {
+  ratio: true,
+  api: true,
+  wall: true,
+  turns: true,
+  avg: true,
+  slow: true,
+  sparkline: true,
+}
+
+export type Timing = {
+  apiMs: number
+  wallMs: number
+  turns: number
+  avgMs: number
+  slowestMs: number
+  apiPct: number
+  durations: number[]
+}
+export const EMPTY: Timing = { apiMs: 0, wallMs: 0, turns: 0, avgMs: 0, slowestMs: 0, apiPct: 0, durations: [] }
+
+export function computeTiming(messages: ReadonlyArray<Message>): Timing {
+  let apiMs = 0
+  let slowestMs = 0
+  let minTs = Number.POSITIVE_INFINITY
+  let maxTs = 0
+  const durations: number[] = []
+
+  for (const msg of messages) {
+    const created = msg.time?.created
+    if (typeof created === "number") {
+      if (created < minTs) minTs = created
+      if (created > maxTs) maxTs = created
+    }
+    if (msg.role === "assistant") {
+      const completed = msg.time?.completed
+      if (typeof completed === "number") {
+        if (completed > maxTs) maxTs = completed
+        const dur = completed - (typeof created === "number" ? created : completed)
+        if (dur > 0) {
+          apiMs += dur
+          durations.push(dur)
+          if (dur > slowestMs) slowestMs = dur
+        }
+      }
+    }
+  }
+
+  const turns = durations.length
+  if (turns === 0) return EMPTY
+  const wallMs = minTs === Number.POSITIVE_INFINITY ? 0 : Math.max(0, maxTs - minTs)
+  return {
+    apiMs,
+    wallMs,
+    turns,
+    avgMs: apiMs / turns,
+    slowestMs,
+    // Summed per-turn inference vs a single wall span: overlapping/retried
+    // assistant records or clock skew can push the ratio past 100%, so clamp it
+    // (the gauge bar clamps too) to keep the percent honest.
+    apiPct: wallMs > 0 ? Math.min(100, Math.round((apiMs / wallMs) * 100)) : 0,
+    durations,
+  }
+}
+
+/** Compact, sidebar-friendly duration: "42s", "6m31s", "1h02m". */
+export function fmtDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms < 0) ms = 0
+  const totalSec = Math.round(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const totalMin = Math.floor(totalSec / 60)
+  if (totalMin < 60) return `${totalMin}m${String(totalSec % 60).padStart(2, "0")}s`
+  const hours = Math.floor(totalMin / 60)
+  return `${hours}h${String(totalMin % 60).padStart(2, "0")}m`
+}
+
+export function bar(pct: number, width: number): string {
+  const p = Math.max(0, Math.min(100, Number.isFinite(pct) ? pct : 0))
+  const filled = Math.round((p / 100) * width)
+  return "█".repeat(filled) + "░".repeat(Math.max(0, width - filled))
+}
+
+export function sparkline(values: number[]): string {
+  if (values.length === 0) return ""
+  const points = values.slice(-SPARK_POINTS)
+  const max = Math.max(...points, 1)
+  return points
+    .map((v) => {
+      const idx = Math.round((v / max) * (SPARK_LEVELS.length - 1))
+      return SPARK_LEVELS[Math.min(SPARK_LEVELS.length - 1, Math.max(0, idx))]
+    })
+    .join("")
+}
+
+/** Join the enabled segments of a packed row with " · ", dropping the empties. */
+function packRow(...segments: string[]): string {
+  return segments.filter(Boolean).join(" · ")
+}
+
+// Every row is a labeled string in the muted tone — no value relies on the
+// reader inferring what an unlabeled number or glyph means. Each field toggles
+// exactly one value; values that share a line drop out individually when their
+// field is off. Fancy and simple render identically except that fancy draws the
+// gauge bar on the ratio row and adds the per-turn sparkline.
+export function buildRows(t: Timing, mode: Mode, fields: Fields): string[] {
+  const rows: string[] = []
+
+  if (fields.ratio) {
+    rows.push(mode === "fancy" ? `api/wall ${bar(t.apiPct, BAR_WIDTH)} ${t.apiPct}%` : `api/wall ${t.apiPct}%`)
+  }
+
+  const timesRow = packRow(
+    fields.api ? `api ${fmtDuration(t.apiMs)}` : "",
+    fields.wall ? `wall ${fmtDuration(t.wallMs)}` : "",
+  )
+  if (timesRow) rows.push(timesRow)
+
+  const turnsRow = packRow(
+    fields.turns ? `turns ${t.turns}` : "",
+    fields.avg ? `avg ${fmtDuration(t.avgMs)}` : "",
+  )
+  if (turnsRow) rows.push(turnsRow)
+
+  if (fields.slow) rows.push(`slowest ${fmtDuration(t.slowestMs)}`)
+
+  if (mode === "fancy" && fields.sparkline) {
+    const spark = sparkline(t.durations)
+    if (spark) rows.push(`per-turn ${spark}`)
+  }
+
+  return rows
+}
+
+export function parseConfig(options: Record<string, unknown> | undefined): { mode: Mode; fields: Fields } {
+  const opts = options ?? {}
+  const mode: Mode = opts.mode === "simple" ? "simple" : "fancy"
+  const fields: Fields = { ...DEFAULT_FIELDS }
+  const raw = opts.fields
+  if (raw && typeof raw === "object") {
+    for (const key of Object.keys(DEFAULT_FIELDS) as (keyof Fields)[]) {
+      const value = (raw as Record<string, unknown>)[key]
+      if (typeof value === "boolean") fields[key] = value
+    }
+  }
+  return { mode, fields }
+}

package/src/tui.tsx

@@ -10,41 +10,35 @@
  * Fancy layout — every value names itself, all rows in the muted tone:
  *
  *   Timing
- *   api/wall ███████░ 78%      gauge: how much of wall-clock was model inference
+ *   api/wall ██████░░ 78%      gauge: how much of wall-clock was model inference
  *   api 31s · wall 40s          the two raw times behind that ratio
  *   turns 4 · avg 8s            completed assistant turns and their average
  *   slowest 19s                 the single slowest turn
  *   per-turn ▄█▂▂               sparkline of each recent turn's duration
  *
- * Metrics (per session):
- *   - api      total assistant inference time = sum of (time.completed - time.created)
- *              over every completed assistant message.
- *   - wall     span from the first to the last message timestamp (includes the time
- *              you spend reading/typing between turns), so api is a fraction of it.
- *   - api/wall api's share of wall-clock, as a bar gauge and percent.
- *   - turns    number of completed assistant messages, plus the average duration.
- *   - slowest  the single slowest assistant message.
- *   - per-turn sparkline of recent per-turn durations.
+ * The timing math, formatting, and config parsing live in `./timing.ts` (pure,
+ * JSX-free, unit-tested); this file is just the Solid component and the slot
+ * registration. See `timing.ts` for the per-session metric definitions.
  *
  * Config — pass options via the tuple form in `tui.json`:
  *
  *   "plugin": [
  *     ["@foae/opencode-timings@latest", {
  *       "mode": "fancy",            // "fancy" (default) | "simple"
- *       "fields": {                  // every field defaults to true
- *         "api": true, "wall": true, "turns": true,
+ *       "fields": {                  // each toggles one value, all default true
+ *         "ratio": true, "api": true, "wall": true, "turns": true,
  *         "avg": true, "slow": true, "sparkline": true
  *       }
  *     }]
  *   ]
  *
- * "fancy" draws a bar gauge for the api/wall ratio and a sparkline of recent
- * turn durations; "simple" is plain labeled rows. The panel is always shown
- * (values read zero before the first turn).
+ * "fancy" draws the gauge bar on the ratio row and adds a sparkline of recent
+ * turn durations; "simple" is the same rows without the bar or sparkline. The
+ * panel is always shown (values read zero before the first turn).
  */
 import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
-import type { Message } from "@opencode-ai/sdk/v2"
-import { createSignal, onCleanup } from "solid-js"
+import { createEffect, createSignal, Index, onCleanup } from "solid-js"
+import { buildRows, computeTiming, EMPTY, parseConfig, type Fields, type Mode, type Timing } from "./timing.ts"
 
 const id = "opencode-timings"
 
@@ -56,150 +50,47 @@ const SIDEBAR_ORDER = 155
 // drive updates; this interval is just a low-frequency backstop.
 const REFRESH_INTERVAL_MS = 15_000
 
-// Narrower than the simple-mode rows so the "api/wall" label + gauge + percent
-// fit one sidebar line without wrapping.
-const BAR_WIDTH = 8
-const SPARK_POINTS = 12
-const SPARK_LEVELS = "▁▂▃▄▅▆▇█"
-
-type Mode = "fancy" | "simple"
-type Fields = {
-  api: boolean
-  wall: boolean
-  turns: boolean
-  avg: boolean
-  slow: boolean
-  sparkline: boolean
-}
-const DEFAULT_FIELDS: Fields = { api: true, wall: true, turns: true, avg: true, slow: true, sparkline: true }
-
-type Timing = {
-  apiMs: number
-  wallMs: number
-  turns: number
-  avgMs: number
-  slowestMs: number
-  apiPct: number
-  durations: number[]
-}
-const EMPTY: Timing = { apiMs: 0, wallMs: 0, turns: 0, avgMs: 0, slowestMs: 0, apiPct: 0, durations: [] }
-
-function computeTiming(messages: ReadonlyArray<Message>): Timing {
-  let apiMs = 0
-  let slowestMs = 0
-  let minTs = Number.POSITIVE_INFINITY
-  let maxTs = 0
-  const durations: number[] = []
-
-  for (const msg of messages) {
-    const created = msg.time?.created
-    if (typeof created === "number") {
-      if (created < minTs) minTs = created
-      if (created > maxTs) maxTs = created
-    }
-    if (msg.role === "assistant") {
-      const completed = msg.time?.completed
-      if (typeof completed === "number") {
-        if (completed > maxTs) maxTs = completed
-        const dur = completed - (typeof created === "number" ? created : completed)
-        if (dur > 0) {
-          apiMs += dur
-          durations.push(dur)
-          if (dur > slowestMs) slowestMs = dur
-        }
-      }
-    }
-  }
-
-  const turns = durations.length
-  if (turns === 0) return EMPTY
-  const wallMs = minTs === Number.POSITIVE_INFINITY ? 0 : Math.max(0, maxTs - minTs)
-  return {
-    apiMs,
-    wallMs,
-    turns,
-    avgMs: apiMs / turns,
-    slowestMs,
-    apiPct: wallMs > 0 ? Math.round((apiMs / wallMs) * 100) : 0,
-    durations,
-  }
-}
-
-/** Compact, sidebar-friendly duration: "42s", "6m31s", "1h02m". */
-function fmtDuration(ms: number): string {
-  if (!Number.isFinite(ms) || ms < 0) ms = 0
-  const totalSec = Math.round(ms / 1000)
-  if (totalSec < 60) return `${totalSec}s`
-  const totalMin = Math.floor(totalSec / 60)
-  if (totalMin < 60) return `${totalMin}m${String(totalSec % 60).padStart(2, "0")}s`
-  const hours = Math.floor(totalMin / 60)
-  return `${hours}h${String(totalMin % 60).padStart(2, "0")}m`
-}
-
-function bar(pct: number, width: number): string {
-  const p = Math.max(0, Math.min(100, Number.isFinite(pct) ? pct : 0))
-  const filled = Math.round((p / 100) * width)
-  return "█".repeat(filled) + "░".repeat(Math.max(0, width - filled))
-}
-
-function sparkline(values: number[]): string {
-  if (values.length === 0) return ""
-  const points = values.slice(-SPARK_POINTS)
-  const max = Math.max(...points, 1)
-  return points
-    .map((v) => {
-      const idx = Math.round((v / max) * (SPARK_LEVELS.length - 1))
-      return SPARK_LEVELS[Math.min(SPARK_LEVELS.length - 1, Math.max(0, idx))]
-    })
-    .join("")
-}
-
-function turnsLine(t: Timing, fields: Fields): string {
-  if (fields.turns && fields.avg) return `turns ${t.turns} · avg ${fmtDuration(t.avgMs)}`
-  if (fields.turns) return `turns ${t.turns}`
-  if (fields.avg) return `avg ${fmtDuration(t.avgMs)}`
-  return ""
-}
-
-// Every row is a labeled string in the muted tone — no value relies on the
-// reader inferring what an unlabeled number or glyph means.
-function buildRows(t: Timing, mode: Mode, fields: Fields): string[] {
-  const rows: string[] = []
-  if (mode === "fancy") {
-    if (fields.api) rows.push(`api/wall ${bar(t.apiPct, BAR_WIDTH)} ${t.apiPct}%`)
-    if (fields.wall) rows.push(`api ${fmtDuration(t.apiMs)} · wall ${fmtDuration(t.wallMs)}`)
-    const ta = turnsLine(t, fields)
-    if (ta) rows.push(ta)
-    if (fields.slow) rows.push(`slowest ${fmtDuration(t.slowestMs)}`)
-    if (fields.sparkline) {
-      const spark = sparkline(t.durations)
-      if (spark) rows.push(`per-turn ${spark}`)
-    }
-  } else {
-    if (fields.api) rows.push(`api ${fmtDuration(t.apiMs)} · ${t.apiPct}% of wall`)
-    if (fields.wall) rows.push(`wall ${fmtDuration(t.wallMs)}`)
-    const ta = turnsLine(t, fields)
-    if (ta) rows.push(ta)
-    if (fields.slow) rows.push(`slowest ${fmtDuration(t.slowestMs)}`)
-  }
-  return rows
-}
-
 function SidebarTimingView(props: {
   api: TuiPluginApi
   sessionID: string
   mode: Mode
   fields: Fields
 }) {
-  const read = (): Timing => computeTiming(props.api.state.session.messages(props.sessionID))
+  // Read defensively: api.state can throw if the session is torn down mid-read
+  // (e.g. deleted from another pane), and this runs inside event/timer callbacks
+  // where an escaping exception would be unhandled — fall back to empty instead.
+  const read = (): Timing => {
+    try {
+      return computeTiming(props.api.state.session.messages(props.sessionID))
+    } catch {
+      return EMPTY
+    }
+  }
   const [timing, setTiming] = createSignal<Timing>(read())
   const refresh = () => setTiming(read())
 
-  // TUI/session state can hydrate asynchronously after mount or a session
-  // switch, so recompute a few times early to recover from empty first reads.
-  const recovery = [setTimeout(refresh, 400), setTimeout(refresh, 1500), setTimeout(refresh, 4000)]
+  // Re-read whenever the active session changes. OpenCode may keep this slot
+  // component mounted and merely swap `session_id`, in which case a mount-time
+  // read alone would keep showing the previous session until the next event or
+  // the interval backstop. Tracking props.sessionID here also re-arms the
+  // async-hydration recovery reads (TUI/session state can land a beat after a
+  // switch), and onCleanup tears the pending timers down on the next switch.
+  createEffect(() => {
+    void props.sessionID // track session switches
+    refresh()
+    const recovery = [setTimeout(refresh, 400), setTimeout(refresh, 1500), setTimeout(refresh, 4000)]
+    onCleanup(() => {
+      for (const timer of recovery) clearTimeout(timer)
+    })
+  })
+
+  // Low-frequency backstop; events drive the timely updates.
   const interval = setInterval(refresh, REFRESH_INTERVAL_MS)
 
+  // Access paths differ by event on purpose: message.updated/session.updated
+  // carry a nested `info` (Message/Session, no top-level sessionID), while
+  // message.removed/session.idle carry sessionID directly — each matches its
+  // SDK event type.
   const unsubscribers = [
     props.api.event.on("message.updated", (event) => {
       if (event.properties?.info?.sessionID === props.sessionID) refresh()
@@ -216,7 +107,6 @@ function SidebarTimingView(props: {
   ]
 
   onCleanup(() => {
-    for (const timer of recovery) clearTimeout(timer)
     clearInterval(interval)
     for (const unsubscribe of unsubscribers) unsubscribe()
   })
@@ -229,30 +119,18 @@ function SidebarTimingView(props: {
         <b>Timing</b>
       </text>
       <box gap={0}>
-        {rows().map((row) => (
-          <text fg={props.api.theme.current.textMuted} wrapMode="none">
-            {row || " "}
-          </text>
-        ))}
+        <Index each={rows()}>
+          {(row) => (
+            <text fg={props.api.theme.current.textMuted} wrapMode="none">
+              {row() || " "}
+            </text>
+          )}
+        </Index>
       </box>
     </box>
   )
 }
 
-function parseConfig(options: Record<string, unknown> | undefined): { mode: Mode; fields: Fields } {
-  const opts = options ?? {}
-  const mode: Mode = opts.mode === "simple" ? "simple" : "fancy"
-  const fields: Fields = { ...DEFAULT_FIELDS }
-  const raw = opts.fields
-  if (raw && typeof raw === "object") {
-    for (const key of Object.keys(DEFAULT_FIELDS) as (keyof Fields)[]) {
-      const value = (raw as Record<string, unknown>)[key]
-      if (typeof value === "boolean") fields[key] = value
-    }
-  }
-  return { mode, fields }
-}
-
 const tui: TuiPlugin = async (api, options) => {
   const { mode, fields } = parseConfig(options)
   api.slots.register({