opencode-models-usage-plugin 0.1.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "opencode-models-usage-plugin",
+  "version": "0.1.0",
+  "description": "Show per-model usage, live TPS, tokens, and cost in the OpenCode sidebar.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    "./tui": {
+      "import": "./src/tui.tsx"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "opencode": ">=1.4.3"
+  },
+  "scripts": {
+    "test": "tsx --test src/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "1.4.3",
+    "@opentui/solid": "0.1.97",
+    "solid-js": "1.9.11"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "tsx": "4.21.0",
+    "typescript": "6.0.2"
+  },
+  "keywords": [],
+  "author": ""
+}

package/src/session-usage.test.ts

@@ -0,0 +1,326 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import { getSessionUsage, getTokenTotal, type SessionMessageLike } from "./session-usage"
+
+test("empty session returns no models", () => {
+  assert.deepEqual(getSessionUsage([]), {
+    models: [],
+  })
+})
+
+test("assistant message contributes all token counters and cost", () => {
+  const usage = getSessionUsage([
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      cost: 0.05,
+      tokens: {
+        input: 11,
+        output: 7,
+        reasoning: 5,
+        cache: {
+          read: 3,
+          write: 2,
+        },
+      },
+    },
+  ])
+
+  assert.deepEqual(usage, {
+    models: [
+      {
+        label: "openai/gpt-4.1",
+        totalTokens: 28,
+        cost: 0.05,
+        tps: 0,
+        isLiveTps: false,
+      },
+    ],
+  })
+})
+
+test("repeated model is listed once while tokens keep accumulating", () => {
+  const messages: SessionMessageLike[] = [
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      cost: 0.01,
+      tokens: {
+        input: 10,
+        output: 5,
+      },
+      time: { created: 1000, completed: 3000 },
+    },
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      cost: 0.02,
+      tokens: {
+        input: 4,
+        output: 6,
+      },
+      time: { created: 4000, completed: 5000 },
+    },
+  ]
+
+  assert.deepEqual(getSessionUsage(messages), {
+    models: [
+      {
+        label: "openai/gpt-4.1",
+        totalTokens: 25,
+        cost: 0.03,
+        tps: 0,
+        isLiveTps: false, // (5 + 6) tokens / (2 + 1) seconds = 11 / 3
+      },
+    ],
+  })
+})
+
+test("multiple models preserve first-seen order", () => {
+  const usage = getSessionUsage([
+    {
+      role: "assistant",
+      providerID: "anthropic",
+      modelID: "claude-sonnet-4",
+      tokens: {
+        input: 1,
+        output: 2,
+      },
+    },
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      tokens: {
+        input: 3,
+        output: 4,
+      },
+    },
+  ])
+
+  assert.deepEqual(usage.models.map((m) => m.label), [
+    "anthropic/claude-sonnet-4",
+    "openai/gpt-4.1",
+  ])
+  assert.equal(usage.models[0].totalTokens, 3)
+  assert.equal(usage.models[1].totalTokens, 7)
+})
+
+test("non-assistant messages are ignored", () => {
+  const usage = getSessionUsage([
+    {
+      role: "user",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      cost: 10,
+      tokens: {
+        input: 999,
+        output: 999,
+      },
+    },
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4.1",
+      cost: 0.1,
+      tokens: {
+        input: 3,
+        output: 2,
+      },
+    },
+  ])
+
+  assert.deepEqual(usage, {
+    models: [
+      {
+        label: "openai/gpt-4.1",
+        totalTokens: 5,
+        cost: 0.1,
+        tps: 0,
+        isLiveTps: false,
+      },
+    ],
+  })
+})
+
+test("provider catalog names are used when available", () => {
+  const providers = {
+    openai: {
+      id: "openai",
+      name: "OpenAI",
+      models: {
+        "gpt-4.1": {
+          id: "gpt-4.1",
+          name: "GPT-4.1",
+        },
+      },
+    },
+  }
+
+  const usage = getSessionUsage(
+    [
+      {
+        role: "assistant",
+        providerID: "openai",
+        modelID: "gpt-4.1",
+        tokens: {
+          input: 2,
+          output: 3,
+        },
+      },
+    ],
+    providers,
+  )
+
+  assert.deepEqual(usage, {
+    models: [
+      {
+        label: "OpenAI/GPT-4.1",
+        totalTokens: 5,
+        cost: 0,
+        tps: 0,
+        isLiveTps: false,
+      },
+    ],
+  })
+})
+
+test("provider catalog also works when providers are stored as an array", () => {
+  const providers = [
+    {
+      id: "anthropic",
+      name: "Anthropic",
+      models: {
+        "claude-sonnet-4": {
+          id: "claude-sonnet-4",
+          name: "Claude Sonnet 4",
+        },
+      },
+    },
+  ]
+
+  const usage = getSessionUsage(
+    [
+      {
+        role: "assistant",
+        providerID: "anthropic",
+        modelID: "claude-sonnet-4",
+        tokens: {
+          input: 4,
+          output: 6,
+        },
+      },
+    ],
+    providers,
+  )
+
+  assert.deepEqual(usage, {
+    models: [
+      {
+        label: "Anthropic/Claude Sonnet 4",
+        totalTokens: 10,
+        cost: 0,
+        tps: 0,
+        isLiveTps: false,
+      },
+    ],
+  })
+})
+
+test("token helper tolerates missing counters", () => {
+  assert.equal(
+    getTokenTotal({
+      input: 1,
+      cache: {
+        read: 2,
+      },
+    }),
+    3,
+  )
+})
+
+test("tps eligibility rules are applied correctly", () => {
+  const usage = getSessionUsage([
+    // valid
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      tokens: { output: 10 },
+      time: { created: 1000, completed: 2000 },
+    },
+    // ignored: summary = true
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      summary: true,
+      tokens: { output: 100 },
+      time: { created: 1000, completed: 2000 },
+    },
+    // ignored: no completed time
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      tokens: { output: 100 },
+      time: { created: 1000 },
+    },
+    // ignored: duration <= 0
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      tokens: { output: 100 },
+      time: { created: 1000, completed: 1000 },
+    },
+    // ignored: generated tokens <= 0
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      tokens: { input: 100, output: 0 },
+      time: { created: 1000, completed: 2000 },
+    },
+    // ignored: finish === "tool-calls"
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      finish: "tool-calls",
+      tokens: { output: 100 },
+      time: { created: 1000, completed: 2000 },
+    },
+    // valid: output + reasoning
+    {
+      role: "assistant",
+      providerID: "openai",
+      modelID: "gpt-4",
+      tokens: { output: 5, reasoning: 5 },
+      time: { created: 2000, completed: 3000 },
+    },
+  ])
+
+  assert.deepEqual(usage, {
+    models: [
+      {
+        label: "openai/gpt-4",
+        totalTokens: 520, // 10 + 100 + 100 + 100 + 100(input) + 100 + 10 = 520 actually wait
+        // Tokens: 10 + 100 + 100 + 100 + 100 + 100 + 10 = 520
+        // Cost: 0
+        // TPS: 20 tokens / 2 seconds = 10
+        cost: 0,
+        tps: 0,
+        isLiveTps: false,
+      },
+    ],
+  })
+  
+  // Update token expectation to match manual addition
+  const total = 10 + 100 + 100 + 100 + 100 + 100 + 10;
+  assert.equal(usage.models[0].totalTokens, total)
+})

package/src/session-usage.ts

@@ -0,0 +1,185 @@
+export interface TokenUsageLike {
+  input?: number | null
+  output?: number | null
+  reasoning?: number | null
+  cache?: {
+    read?: number | null
+    write?: number | null
+  } | null
+}
+
+export interface SessionMessageLike {
+  id?: string
+  role: string
+  modelID?: string | null
+  providerID?: string | null
+  tokens?: TokenUsageLike | null
+  cost?: number | null
+  summary?: unknown
+  time?: {
+    created?: number | null
+    completed?: number | null
+  } | null
+  finish?: string | null
+}
+
+export interface ModelUsage {
+  label: string
+  tps: number
+  totalTokens: number
+  cost: number
+  isLiveTps?: boolean
+}
+
+export interface SessionUsage {
+  models: ModelUsage[]
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+const toNumber = (value: unknown): number =>
+  typeof value === "number" && Number.isFinite(value) ? value : 0
+
+const getStringProp = (value: unknown, key: string): string | undefined => {
+  if (!isRecord(value)) {
+    return undefined
+  }
+
+  const prop = value[key]
+  return typeof prop === "string" ? prop : undefined
+}
+
+const getObjectProp = (value: unknown, key: string): unknown => {
+  if (!isRecord(value)) {
+    return undefined
+  }
+
+  return value[key]
+}
+
+const findProvider = (providers: unknown, providerID: string): unknown => {
+  if (Array.isArray(providers)) {
+    return providers.find((provider) => getStringProp(provider, "id") === providerID)
+  }
+
+  return getObjectProp(providers, providerID)
+}
+
+const findModel = (models: unknown, modelID: string): unknown => {
+  if (Array.isArray(models)) {
+    return models.find((model) => getStringProp(model, "id") === modelID)
+  }
+
+  return getObjectProp(models, modelID)
+}
+
+export const resolveModelLabel = (
+  modelID: string,
+  providerID: string | undefined,
+  providers: unknown,
+): string => {
+  if (!providerID) {
+    return modelID
+  }
+
+  const provider = findProvider(providers, providerID)
+  const providerName = getStringProp(provider, "name") ?? providerID
+  const model = findModel(getObjectProp(provider, "models"), modelID)
+  const modelName = getStringProp(model, "name") ?? modelID
+
+  return `${providerName}/${modelName}`
+}
+
+export const getTokenTotal = (tokens?: TokenUsageLike | null): number =>
+  toNumber(tokens?.input) +
+  toNumber(tokens?.output) +
+  toNumber(tokens?.reasoning) +
+  toNumber(tokens?.cache?.read) +
+  toNumber(tokens?.cache?.write)
+
+export interface LiveTpsState {
+  modelID: string
+  providerID: string | undefined
+  tpsTokens: number
+  tpsDurationMs: number
+}
+
+export const getSessionUsage = (
+  messages: ReadonlyArray<SessionMessageLike>,
+  providers?: unknown,
+  liveTps?: LiveTpsState | null,
+): SessionUsage => {
+  const modelStats = new Map<string, {
+    label: string
+    totalTokens: number
+    cost: number
+  }>()
+  const modelsUsed: string[] = []
+
+  for (const message of messages) {
+    if (message.role !== "assistant") {
+      continue
+    }
+
+    const modelID = typeof message.modelID === "string" ? message.modelID : undefined
+    if (!modelID) {
+      continue
+    }
+
+    const providerID =
+      typeof message.providerID === "string" ? message.providerID : undefined
+    const modelKey = providerID ? `${providerID}:${modelID}` : modelID
+
+    if (!modelStats.has(modelKey)) {
+      modelStats.set(modelKey, {
+        label: resolveModelLabel(modelID, providerID, providers),
+        totalTokens: 0,
+        cost: 0,
+      })
+      modelsUsed.push(modelKey)
+    }
+
+    const stats = modelStats.get(modelKey)!
+    stats.totalTokens += getTokenTotal(message.tokens)
+    stats.cost += toNumber(message.cost)
+  }
+
+  // Inject live TPS
+  let liveTpsKey: string | undefined
+  if (liveTps && liveTps.modelID) {
+    const providerID = liveTps.providerID
+    const modelID = liveTps.modelID
+    liveTpsKey = providerID ? `${providerID}:${modelID}` : modelID
+    if (!modelStats.has(liveTpsKey)) {
+      modelStats.set(liveTpsKey, {
+        label: resolveModelLabel(modelID, providerID, providers),
+        totalTokens: 0,
+        cost: 0,
+      })
+      modelsUsed.push(liveTpsKey)
+    }
+  }
+
+  const models = modelsUsed.map((key) => {
+    const stats = modelStats.get(key)!
+    let isLiveTps = false
+    let tps = 0
+
+    if (key === liveTpsKey && liveTps) {
+      isLiveTps = true
+      const durationSeconds = liveTps.tpsDurationMs / 1000
+      tps = durationSeconds > 0 ? liveTps.tpsTokens / durationSeconds : 0
+    }
+
+    return {
+      label: stats.label,
+      totalTokens: stats.totalTokens,
+      cost: stats.cost,
+      tps,
+      isLiveTps,
+    }
+  })
+
+  return { models }
+}

package/src/tui.tsx

@@ -0,0 +1,230 @@
+/** @jsxImportSource @opentui/solid */
+
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { For, createMemo, createSignal, onMount, onCleanup } from "solid-js"
+
+import { getSessionUsage, type SessionMessageLike, type LiveTpsState } from "./session-usage"
+
+const pluginID = "local:session-model-usage"
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+const mapMessage = (message: unknown): SessionMessageLike => {
+  if (!isRecord(message)) {
+    return { role: "unknown" }
+  }
+
+  return {
+    id: typeof message.id === "string" ? message.id : undefined,
+    role: typeof message.role === "string" ? message.role : "unknown",
+    modelID: typeof message.modelID === "string" ? message.modelID : undefined,
+    providerID: typeof message.providerID === "string" ? message.providerID : undefined,
+    tokens: isRecord(message.tokens) ? message.tokens : undefined,
+    cost: typeof message.cost === "number" ? message.cost : undefined,
+    summary: message.summary,
+    time: isRecord(message.time)
+      ? {
+          created:
+            typeof message.time.created === "number" ? message.time.created : undefined,
+          completed:
+            typeof message.time.completed === "number" ? message.time.completed : undefined,
+        }
+      : undefined,
+    finish: typeof message.finish === "string" ? message.finish : undefined,
+  }
+}
+
+const mapMessages = (messages: readonly unknown[]): SessionMessageLike[] => {
+  return messages.map((message) => mapMessage(message))
+}
+
+const useSessionMessages = (api: TuiPluginApi, rootSessionID: string) => {
+  const [extraMessages, setExtraMessages] = createSignal<SessionMessageLike[]>([])
+  const [trackedSessionIDs, setTrackedSessionIDs] = createSignal<ReadonlySet<string>>(
+    new Set([rootSessionID]),
+  )
+  
+  const [liveInfo, setLiveInfo] = createSignal<{
+    messageID: string;
+    modelID: string;
+    providerID?: string;
+    startTime: number;
+    chars: number;
+  } | null>(null)
+
+  const fetchChildrenMessages = async (
+    sessionID: string,
+    visited = new Set<string>(),
+  ): Promise<{ messages: SessionMessageLike[]; sessionIDs: Set<string> }> => {
+    if (visited.has(sessionID)) {
+      return { messages: [], sessionIDs: visited }
+    }
+
+    visited.add(sessionID)
+    const res = await api.client.session.children({ sessionID })
+    if (res.error || !res.data) {
+      return { messages: [], sessionIDs: visited }
+    }
+
+    let msgs: SessionMessageLike[] = []
+    for (const child of res.data) {
+      const childID = child.id
+      visited.add(childID)
+      const mRes = await api.client.session.messages({ sessionID: childID })
+      if (!mRes.error && mRes.data) {
+        msgs.push(...mapMessages(mRes.data.map((message) => message.info)))
+      }
+      const nested = await fetchChildrenMessages(childID, visited)
+      msgs.push(...nested.messages)
+    }
+    return { messages: msgs, sessionIDs: visited }
+  }
+
+  const reloadExtraMessages = async () => {
+    const result = await fetchChildrenMessages(rootSessionID)
+    setExtraMessages(result.messages)
+    setTrackedSessionIDs(new Set(result.sessionIDs))
+  }
+
+  onMount(() => {
+    reloadExtraMessages()
+
+    const unsubs = [
+      api.event.on("message.part.delta", (ev) => {
+        const { sessionID, messageID, field, delta } = ev.properties
+        if (!sessionID || !messageID || typeof delta !== "string") return
+        if (field !== "text" && field !== "reasoning") return
+
+        setLiveInfo(prev => {
+          if (prev?.messageID === messageID) {
+            return { ...prev, chars: prev.chars + delta.length }
+          }
+
+          // Try to find the message
+          const rootMsgs = mapMessages(api.state.session.messages(rootSessionID))
+          const extra = extraMessages()
+          let found = rootMsgs.find(m => m.id === messageID)
+          if (!found) {
+            found = extra.find(m => m.id === messageID)
+          }
+
+          if (!found || found.role !== "assistant" || !found.modelID) {
+            return prev
+          }
+
+          const modelID = found.modelID
+          if (typeof modelID !== "string") {
+            return prev
+          }
+
+          return {
+            messageID,
+            modelID,
+            providerID: typeof found.providerID === "string" ? found.providerID : undefined,
+            startTime: Date.now(),
+            chars: delta.length
+          }
+        })
+      }),
+      api.event.on("message.updated", () => reloadExtraMessages()),
+      api.event.on("session.status", () => reloadExtraMessages()),
+      api.event.on("session.idle", (ev) => {
+        if (!trackedSessionIDs().has(ev.properties.sessionID)) {
+          return
+        }
+
+        setLiveInfo(null)
+      })
+    ]
+
+    onCleanup(() => {
+      unsubs.forEach(u => u())
+    })
+  })
+
+  // Derive liveTps from liveInfo
+  const [now, setNow] = createSignal(Date.now())
+  
+  onMount(() => {
+    const timer = setInterval(() => setNow(Date.now()), 500)
+    onCleanup(() => clearInterval(timer))
+  })
+
+  const liveTps = createMemo<LiveTpsState | null>(() => {
+    const info = liveInfo()
+    if (!info) return null
+
+    const durationMs = now() - info.startTime
+    // Estimate 1 token = 4 chars approx during streaming
+    const tpsTokens = Math.ceil(info.chars / 4)
+
+    return {
+      modelID: info.modelID,
+      providerID: info.providerID,
+      tpsTokens,
+      tpsDurationMs: Math.max(durationMs, 1)
+    }
+  })
+
+  return { extraMessages, liveTps }
+}
+
+const SessionUsagePanel = (props: { api: TuiPluginApi; sessionID: string }) => {
+  const { extraMessages, liveTps } = useSessionMessages(props.api, props.sessionID)
+  
+  const usage = createMemo(() => {
+    const rootMsgs = mapMessages(props.api.state.session.messages(props.sessionID))
+    const allMsgs = [...rootMsgs, ...extraMessages()]
+    return getSessionUsage(allMsgs, props.api.state.provider, liveTps())
+  })
+
+  return (
+    <box flexDirection="column">
+      <text>📊 Models Usages</text>
+      {usage().models.length === 0 ? (
+        <text>None yet</text>
+      ) : (
+        <For each={usage().models}>
+          {(model) => (
+            <box flexDirection="column">
+              <text>● {model.label}</text>
+              <box flexDirection="column" paddingLeft={2}>
+                <box flexDirection="row">
+                  <text>■ TPS </text>
+                  <text fg="gray">{model.isLiveTps && model.tps > 0 ? model.tps.toFixed(1) : "—"}</text>
+                </box>
+                <box flexDirection="row">
+                  <text>■ Total Tokens </text>
+                  <text fg="gray">{model.totalTokens.toLocaleString("en-US")}</text>
+                </box>
+                <box flexDirection="row">
+                  <text>■ spent </text>
+                  <text fg="gray">${model.cost.toFixed(4)}</text>
+                </box>
+              </box>
+            </box>
+          )}
+        </For>
+      )}
+    </box>
+  )
+}
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    order: 150,
+    slots: {
+      sidebar_content(_ctx, props) {
+        return <SessionUsagePanel api={api} sessionID={props.session_id} />
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: pluginID,
+  tui,
+}
+
+export default plugin