@glaicer/supercode-token-usage-panel 1.0.0 → 1.2.0

package/README.md

@@ -13,7 +13,7 @@ Requires OpenCode v2 (`>=2.0.0`). On OpenCode v1 stay on `@glaicer/supercode-tok
 
 ## Install
 
-Install with the OpenCode CLI — it installs the package and registers the plugin in the global CLI configuration (`~/.config/opencode/cli.json`):
+Install with the OpenCode CLI — it installs the package and registers the plugin in the global server configuration (`~/.config/opencode/opencode.jsonc`):
 
 ```bash
 opencode plugin add @glaicer/supercode-token-usage-panel
@@ -24,7 +24,7 @@ Restart OpenCode after installing.
 > [!IMPORTANT]
 > **The first OpenCode load after installing this plugin may be slow.** That's OpenCode downloading the plugin's packages and managed tools into its cache — it happens once. Every subsequent start is fast.
 
-Manual install also works: add the package to the `plugins` array in `~/.config/opencode/cli.json`:
+Manual install also works: add the package to the `plugins` array in `~/.config/opencode/opencode.jsonc`:
 
 ```jsonc
 {
@@ -32,6 +32,22 @@ Manual install also works: add the package to the `plugins` array in `~/.config/
 }
 ```
 
+### Sidebar order
+
+The panel claims `after: "sidebar.content"`, and so do other plugins that extend the sidebar, so their relative order is the order in which they were registered. Entries in `opencode.jsonc` are always ordered before entries in `cli.json`, so register the panel here to place it relative to another sidebar plugin — for example, between `context-progress-bar` and `session-recap`:
+
+```jsonc
+{
+  "plugins": [
+    "@glaicer/supercode-context-progress-bar",
+    "@glaicer/supercode-token-usage-panel",
+    "@glaicer/supercode-session-recap"
+  ]
+}
+```
+
+The package ships a no-op server entry purely to make this possible: a `./tui`-only package can only be registered in `cli.json`, which always sorts last.
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Server entrypoint (required so the plugin loads at all).
+ *
+ * The panel itself is TUI-only; all behaviour lives in `src/usage-panel.tsx`.
+ * This no-op server half exists for two host requirements: the server resolves
+ * a package through its main/server entry and only then reports `features.tui`,
+ * and sidebar claims from different plugins share one slot, so their relative
+ * order is the order of the `plugins` array that loaded them. Registering in
+ * `opencode.jsonc` is therefore the only way to place this panel relative to
+ * another `sidebar.content` claim such as session-recap — a `cli.json`-only
+ * entry is always ordered last.
+ */
+import { Plugin } from "@opencode/plugin";
+export default Plugin.define({
+  id: "supercode.token-usage",
+  setup() {}
+});

package/dist/usage-model.js

@@ -6,9 +6,9 @@
  * deltas. Exposes only ready-to-render rows plus a state flag.
  *
  * OpenCode v2 shape: one assistant message = one model step, so per-step tokens
- * live on `message.tokens` (there are no `step-finish` parts) and TTFT is
- * `message.time.streamed - message.time.created` (`time.streamed` is set by
- * `session.step.streamed`, the first streamed token).
+ * live on `message.tokens` (there are no `step-finish` parts). `time.streamed`
+ * marks the end of the provider stream; first output comes from content-start
+ * events or the timestamp of the first reasoning/tool content item.
  */
 
 export const USAGE_SECTION_TITLE = "Token Usage";
@@ -180,7 +180,7 @@ function addTotals(target, source) {
 function finishedStep(message) {
   return message.tokens !== undefined || message.time.completed !== undefined;
 }
-function completedMetrics(messages) {
+function completedMetrics(messages, firstOutputs) {
   const result = emptyMetrics();
   for (const info of messages) {
     if (info.type !== "assistant") continue;
@@ -198,24 +198,16 @@ function completedMetrics(messages) {
     if (info.tokens && !stepHasTool) {
       addCalibration(result.calibrations, modelKey(info), stepChars, info.tokens.output + info.tokens.reasoning);
     }
-
-    // Without streamed timing there is no first-token sample and no decode
-    // baseline, so the step contributes steps/calibration only.
     const streamed = info.time.streamed;
     if (!positive(streamed ?? 0)) continue;
-    const visible = info.content.some(item => item.type === "text" || item.type === "reasoning");
-    if (!visible) continue;
-    const ttft = streamed - info.time.created;
-    if (!positive(ttft)) continue;
+    const head = info.content[0];
+    const first = firstOutputs.get(info.id) ?? (head && head.type !== "text" ? head.time?.created : undefined);
+    if (first === undefined || first < info.time.created || first > streamed) continue;
+    const ttft = first - info.time.created;
     result.ttftMs += ttft;
     result.ttftCount++;
     const generated = info.tokens ? info.tokens.output + info.tokens.reasoning : 0;
-    const tools = info.content.reduce((sum, item) => {
-      if (item.type !== "tool" || item.state.status !== "completed") return sum;
-      const duration = (item.time.completed ?? 0) - (item.time.ran ?? item.time.created);
-      return positive(duration) ? sum + duration : sum;
-    }, 0);
-    const decode = info.time.completed - info.time.created - ttft - tools;
+    const decode = streamed - first;
     if (!positive(generated) || !positive(decode)) continue;
     result.generated += generated;
     result.decodeMs += decode;
@@ -282,10 +274,10 @@ async function listAllMessages(client, sessionID) {
   } while (cursor);
   return collected.sort((a, b) => (a.time.created ?? 0) - (b.time.created ?? 0));
 }
-async function fetchContribution(client, session) {
+async function fetchContribution(client, session, firstOutputs) {
   let metrics = emptyMetrics();
   try {
-    metrics = completedMetrics(await listAllMessages(client, session.id));
+    metrics = completedMetrics(await listAllMessages(client, session.id), firstOutputs);
   } catch {
     // Totals stay usable when diagnostic history cannot be read.
   }
@@ -297,7 +289,7 @@ async function fetchContribution(client, session) {
     } : {})
   };
 }
-async function fetchBranch(client, root) {
+async function fetchBranch(client, root, firstOutputs) {
   const contributions = new Map();
   const incompleteBranches = new Set();
   const queue = [root];
@@ -306,7 +298,7 @@ async function fetchBranch(client, root) {
     const session = queue.shift();
     if (visited.has(session.id)) continue;
     visited.add(session.id);
-    contributions.set(session.id, await fetchContribution(client, session));
+    contributions.set(session.id, await fetchContribution(client, session, firstOutputs));
     try {
       const children = (await client.session.list({
         parentID: session.id
@@ -342,7 +334,7 @@ function belongsToBranch(sessionID, rootID, contributions) {
  * all descendants (subagents). The walk counts each session once and keeps
  * resolved aggregates when a branch fails to resolve.
  */
-async function fetchFamily(client, sessionID) {
+async function fetchFamily(client, sessionID, firstOutputs) {
   let root = await client.session.get({
     sessionID
   });
@@ -356,7 +348,7 @@ async function fetchFamily(client, sessionID) {
     if (!parent) throw new Error("parent session unavailable");
     root = parent;
   }
-  return fetchBranch(client, root);
+  return fetchBranch(client, root, firstOutputs);
 }
 
 /**
@@ -393,6 +385,7 @@ export function createUsageModel(api, sessionId, solid) {
   const tombstones = new Set();
   /** Content items whose stream already ended; stale deltas must not restart them. */
   const endedParts = new Set();
+  const firstOutputs = new Map();
   let timer;
   let ttftTurnShown = false;
   let members = new Set();
@@ -499,7 +492,7 @@ export function createUsageModel(api, sessionId, solid) {
       sessionID,
       startRevision: appliedRevision
     };
-    void fetchFamily(api.client, sessionID).then(family => {
+    void fetchFamily(api.client, sessionID, firstOutputs).then(family => {
       if (!isFresh(freshness)) return;
       setRemote(previous => {
         const contributions = new Map(family.contributions);
@@ -564,6 +557,7 @@ export function createUsageModel(api, sessionId, solid) {
     failedMembers.clear();
     tombstones.clear();
     endedParts.clear();
+    firstOutputs.clear();
     setRemote(undefined);
     solid.untrack(() => {
       const turn = scanTurnState(sessionID);
@@ -600,7 +594,7 @@ export function createUsageModel(api, sessionId, solid) {
       sessionID: memberID
     }).then(data => {
       if (!data) throw new Error("session unavailable");
-      return fetchContribution(api.client, data);
+      return fetchContribution(api.client, data, firstOutputs);
     }).then(contribution => {
       if (memberRequests.get(memberID) !== memberRequest) return;
       mergeContributions(new Map([[memberID, contribution]]), freshness);
@@ -619,7 +613,7 @@ export function createUsageModel(api, sessionId, solid) {
       sessionID: branchID
     }).then(root => {
       if (!root) throw new Error("session unavailable");
-      return fetchBranch(api.client, root);
+      return fetchBranch(api.client, root, firstOutputs);
     }).then(branch => {
       setRemote(previous => {
         if (!isCurrent(previous, freshness) || branchRequests.get(branchID) !== branchRequest || !previous.contributions) {
@@ -757,6 +751,7 @@ export function createUsageModel(api, sessionId, solid) {
       assistantMessageID,
       started
     } = event.data;
+    if (members.has(sessionID)) firstOutputs.delete(assistantMessageID);
     if (sessionID !== sessionId()) return;
     if (ttftTurnShown) return;
     ttftTurnShown = true;
@@ -779,6 +774,18 @@ export function createUsageModel(api, sessionId, solid) {
     if (sessionID !== sessionId()) return;
     if (liveTtft()?.messageID === assistantMessageID) clearLiveTtft();
   });
+  const onOutputStarted = event => {
+    const {
+      sessionID,
+      assistantMessageID
+    } = event.data;
+    if (!members.has(sessionID)) return;
+    if (!firstOutputs.has(assistantMessageID)) firstOutputs.set(assistantMessageID, event.created);
+    if (sessionID === sessionId() && liveTtft()?.messageID === assistantMessageID) clearLiveTtft();
+  };
+  const offTextStarted = api.data.on("session.text.started", onOutputStarted);
+  const offReasoningStarted = api.data.on("session.reasoning.started", onOutputStarted);
+  const offToolInputStarted = api.data.on("session.tool.input.started", onOutputStarted);
   const onStepSettled = (sessionID, assistantMessageID) => {
     if (sessionID === sessionId()) {
       if (liveTtft()?.messageID === assistantMessageID) clearLiveTtft();
@@ -882,6 +889,9 @@ export function createUsageModel(api, sessionId, solid) {
     offStepStarted();
     offExecutionStarted();
     offStepStreamed();
+    offTextStarted();
+    offReasoningStarted();
+    offToolInputStarted();
     offStepEnded();
     offStepFailed();
     offTextDelta();

package/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Root server entry for local-directory loading.
+ *
+ * When this package is referenced by directory path in `opencode.json(c)`
+ * `plugins`, the host loads `<dir>/index.{ts,js}` directly and does not consult
+ * `package.json` `exports`. The npm route keeps using `exports["."]` →
+ * `./dist/index.js`. Both entries define the same plugin; the host loads
+ * exactly one per package.
+ */
+export { default } from "./dist/index.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@glaicer/supercode-token-usage-panel",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "OpenCode TUI sidebar section: cumulative token usage and cost of the current session family.",
   "type": "module",
   "license": "MIT",
@@ -21,10 +21,14 @@
     "generation-speed"
   ],
   "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/index.js",
     "./tui": "./dist/usage-panel.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "index.ts",
+    "tui.js"
   ],
   "publishConfig": {
     "access": "public"

package/tui.js

@@ -0,0 +1,3 @@
+// Local-install entry: a directory plugin target resolves "<dir>/tui.*"
+// instead of package.json exports["./tui"]; npm installs use the export.
+export { default } from "./dist/usage-panel.js";