opencode-usage-insights 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Batista
+
+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

@@ -1,3 +1,320 @@
-# Temporary Holding Version
+# opencode-usage-insights 📊
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![GitHub Tag](https://img.shields.io/github/v/tag/hugobatista/opencode-usage-insights?logo=github&label=latest)](https://github.com/hugobatista/opencode-usage-insights/releases)
+[![Test](https://img.shields.io/github/actions/workflow/status/hugobatista/opencode-usage-insights/test.yml?label=Test)](https://github.com/hugobatista/opencode-usage-insights/actions/workflows/test.yml)
+[![Lint](https://img.shields.io/github/actions/workflow/status/hugobatista/opencode-usage-insights/lint.yml?label=Lint)](https://github.com/hugobatista/opencode-usage-insights/actions/workflows/lint.yml)
+[![npm](https://img.shields.io/npm/v/opencode-usage-insights.svg)](https://www.npmjs.com/package/opencode-usage-insights)
+
+OpenCode plugin for one question the host cannot answer: **which endpoint is
+actually serving each model** — and what that costs. It shows a telemetry line
+above the composer after every finished turn and records every assistant step
+in a local SQLite file, read back through an interactive `/usage` panel.
+
+![The telemetry line after a turn](docs/images/line.png)
+
+Everything stays local: one SQLite file under the OpenCode state directory,
+written by the server-side recorder and read by the TUI.
+
+## What it does
+
+- **The line** (`session.composer.top`): end time, the gap since the previous
+  prompt, the endpoint that served the turn, turn and session token totals, and
+  warnings when the prompt cache or the endpoint identity changed. It belongs to
+  finished work, so it stays hidden while a turn is running.
+- **The `/usage` panel**: ten keyboard-driven views — `overview`, `models`,
+  `endpoints`, `affinity`, `cache`, `periods`, `latency`, `sessions`, `turns`,
+  `db` — over five ranges (`session`, `today`, `7d`, `30d`, `all`), with
+  drill-downs, sorting, filters and state remembered between openings.
+  `/usage models 7d`, `/usage affinity`, `/usage endpoints 30d`.
+- **The session sidebar**: the session's own totals and its last turns, in the
+  same buckets as the line. Three lines per turn — when and through what, the
+  prompt volumes, then `hit · tok/s · cost` — and the session's average
+  throughput on its totals:
+  `16:54 orcarouter-dsv4.1flash` / `in 1.7k (427.3k) · out 1.06k` /
+  `hit 99.7% · 1.2k/s · $0.0006`.
+- **The record** (server entry): every assistant step with tokens, cost,
+  timings, finish reason, provider/model, session and parent ids, and the
+  endpoint that served it; prompts, session lifecycle and compaction events too.
+- **Portable data** (from a checkout): `bun run report --ndjson` exports the
+  whole database, and `--import` merges it back on another machine.
+- **Observational by design**: the plugin never rewrites prompts, requests or
+  responses, and a failure inside the recorder is swallowed — telemetry can
+  never interrupt a session.
+
+## Requirements
+
+- **OpenCode V2** (`>=2.0.0`). The V2 release changed the plugin API (slots,
+  panels, event stream).
+- [Bun](https://bun.sh) to install dependencies (development only).
+
+| | |
+| --- | --- |
+| **OS** | Linux, macOS and Windows. The database lives in the per-user state directory of each (table below). CI runs the data layer — paths, database, recorder, queries, panel assembly, dump round-trip, file permissions — on all three, and the whole suite (including the TUI render tests) on Linux. `bun run check:platform` runs that same check by hand. |
+| **Runtime** | Bun, the runtime OpenCode ships with. SQLite comes from `bun:sqlite`: there is no native module to build and nothing to compile on install. |
+
+## Install
+
+> [!IMPORTANT]
+> **Not on the npm registry yet.** Until the first release is published,
+> `opencode plugin add` and the package-name form below cannot resolve it — use
+> the local checkout, the last form of this section.
+
+```sh
+opencode plugin add opencode-usage-insights
+```
+
+Or add the package to `~/.config/opencode/opencode.jsonc` (server entry) and
+`~/.config/opencode/cli.json` (TUI entry):
+
+```jsonc
+// ~/.config/opencode/opencode.jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-usage-insights"]
+}
+```
+
+```jsonc
+// ~/.config/opencode/cli.json
+{
+  "$schema": "https://opencode.ai/v2/cli.json",
+  "plugins": ["opencode-usage-insights"]
+}
+```
+
+To pass [options](#configuration), use the object form:
+
+```jsonc
+{
+  "plugins": [
+    { "package": "opencode-usage-insights", "options": { "identity": "endpoint" } }
+  ]
+}
+```
+
+Or register a local checkout. V2 resolves a local *directory* plugin through its
+entry files, so pointing at `src/` loads the server recorder (`src/index.ts`)
+and the TUI contributions (`src/tui.tsx`) from source:
+
+```jsonc
+// ~/.config/opencode/opencode.jsonc
+{ "plugins": [{ "package": "/home/you/code/projects/opencode-usage-insights/src" }] }
+```
+
+```jsonc
+// ~/.config/opencode/cli.json
+{ "plugins": [{ "package": "/home/you/code/projects/opencode-usage-insights/src" }] }
+```
+
+Configuration changes reload on their own; after changing the plugin's source,
+restart the background service with `opencode service restart`.
+
+Send a prompt to verify: the telemetry line appears above the composer when the
+turn finishes, and `/usage` (alias `/insights`) opens the panel.
+
+## The line
+
+```text
+14:32:07 · Δ 3m12s · orcarouter-dsv4.1-flash-free · in 85.4k (1.62M), cached 1.53M, out 3.7k · sess in 2.1M (14.5M), cached 12.4M, out 88k · ⚠ cache expired (−11.7k)
+```
+
+| Segment | Meaning |
+| --- | --- |
+| `14:32:07` | When the response ended (`completed`, else `streamed`, else `created`). |
+| `Δ 3m12s` | Time since the previous prompt of the same session. |
+| `orcarouter-dsv4.1-flash-free` | The endpoint that served the turn (`identity: "endpoint"`, the default): the gateway names it in a response header, or the request host names the operator. Without one the segment falls back to `providerID/modelID` (variant as a trailing word); `identity: "model"` always shows that form. Yellow with `changed` when it differs from the previous prompt. |
+| `in 85.4k (1.62M), cached 1.53M, out 3.7k` | `in` is the uncached part of the prompt (fresh input + cache writes), the parenthesised value the whole prompt — shown only when the two differ — `cached` its cached part, and `out` everything generated (visible output + reasoning). With several steps the segment reads `3 steps · …` and reports the step the turn ended with (`latest`); `turnTotals: "sum"` adds every step instead. |
+| `sess in 2.1M (14.5M), cached 12.4M, out 88k` | The session totals reported by the host, in the same buckets. |
+| `⚠ cache expired (−11.7k)` | Yellow. The prompt cache read fell by that many tokens against a comparable previous step; `×N` when several steps in the turn lost cache. |
+
+The turn segment carries no label by default — the numbers are the turn's, and
+`sess` marks the session's; `labels.turn` (e.g. `"turn"`) brings a prefix back.
+
+A turn is every consecutive assistant step after a prompt. Compaction, shell,
+`idle` and info messages do not split a turn; `user`, `synthetic` and `system`
+messages do. From a checkout, `bun run demo` prints one example per case,
+including the streaming one and both turn-total views.
+
+## The panel
+
+`/usage [view] [range]` opens the panel (`/usage` alone opens the last view, or
+`overview` over `all` the first time). While the panel is open it owns input, so
+the prompt cannot take the command again: `escape` closes it, `f` toggles full
+screen, and the palette entry (`ctrl+p` → "Usage insights") toggles it closed.
+With the composer focused, `/usage` with no arguments also toggles it closed,
+and any argument — including an unknown token, which is ignored — keeps it open.
+There is no default key binding — the command is palette-only, so it never
+shadows a key you use.
+
+![The /usage endpoints view](docs/images/panel-endpoints.png)
+
+The view bar at the top names every view and brackets the active one; `?` opens
+a help overlay that repeats the keys and defines every number.
+
+### Keys
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` / `j` `k` | Move the cursor; the row under it is highlighted. |
+| `pageup` `pagedown` / `home` `end` | Move by ten rows / to the first or last row. |
+| `enter` | Drill into the row: a model → the endpoints that served it and its affinity; an endpoint → the models it served and its latency; a session → its turns; a period → the models of the period. In `db`, prune the steps recorded before the selected retention's cutoff date (asks first). |
+| `backspace` | Go back from a drill-down. |
+| `0`–`9` / `[` `]` | Pick a view (`0` is `db`) / cycle views. |
+| `t` / `shift+t` | Next / previous range. |
+| `s` / `shift+s` | Cycle the sort column / reverse it. |
+| `b` | `periods` bucket: day → week → month. |
+| `a` | `turns` scope: this session ↔ every session. |
+| `m` `e` | Filter by model or by **endpoint** (a picker of the values actually observed). |
+| `x` | Clear the filters. |
+| `r` | Re-read the database. |
+| `v` | `db`: compact the file, giving the space of deleted rows back. |
+| `?` | Help overlay. |
+| `f` / `escape` | Full screen / close. |
+
+The view, range, sort, bucket, scope and filters are stored through the host's
+durable storage, so the panel reopens where it was left.
+
+### Views
+
+| View | Answers |
+| --- | --- |
+| `overview` | Steps, sessions, prompts, `in`/`cached`/`write`/`out`, `hit`, cost, an activity sparkline, a `this session` block and a **data coverage** block (how many steps lack a model, an endpoint or a completion — a zero elsewhere is only trustworthy when this is complete). |
+| `models` | Every model with its cache (`hit` and the per-step `hit p50`), tokens, cost, the **endpoints that actually served it** and how often its identity changed. `enter` opens the per-endpoint detail. |
+| `endpoints` | **Who served the work**: one row per routing endpoint, with the models it served, steps, share, prompt, cached, `hit`, p50 throughput, wall time and cost. `enter` lists every model it served. A request whose endpoint was never observed is dimmed — the panel does not invent an identity. |
+| `affinity` | How often the step's identity changed against the step before it in the same session — the model and the endpoint — the cache those changes cost, and the most frequent transitions. |
+| `cache` | Reuse by model, losses grouped by reason (`expired`, `compaction`, `unknown`), **cache survival against idle time**, reuse kept per endpoint, the observed TTL bounds (`hits up to` / `drops from`) and the most recent losses. |
+| `periods` | Day, week or month totals — steps, sessions, `in`, `cached`, `write`, `hit`, `out`, cost — with a sparkline per metric and a totals row. `enter` lists the models of a period. |
+| `latency` | Wall time, streaming window and throughput as p50/p90/p99 overall and per model (per endpoint when a model is filtered). `n < 5` is dimmed. |
+| `sessions` | Each session with steps, prompts, tokens, `hit`, cost, its directory and how many models it used; subagent sessions are indented under their parent and rolled up. |
+| `turns` | The per-prompt history: one line per finished turn, rendered exactly like the live line. `a` widens it to every session, titled. |
+| `db` | Where the file lives, what it holds and how much of it is old. The retention table lists, per preset (`30`/`90`/`365` days), how many steps a prune would remove and the cutoff date it prunes from — pick one with `↑`/`↓` and `enter` prunes it (a confirmation first); `v` gives the space back. |
+
+The panel sums the stored per-step buckets over the selected range, so a number
+read in one place means the same in the other: `prompt` is everything the
+provider saw (`cached + fresh + writes`), `in` the uncached part, `hit` is
+`cached / prompt`, and `out` everything generated (visible output + reasoning).
+
+The endpoint is what the gateway names in `x-opencode-endpoint-id`, or the host
+of a per-operator provider. A **gateway host is not an endpoint**: when the
+gateway names no downstream endpoint, the request has no observed endpoint and
+the views say so (`– (never observed)`) instead of showing the gateway's name as
+if it had run the model. The line and the sidebar then fall back to
+`provider/model`. The line reports the endpoint of the turn it belongs to: a
+turn the gateway did not name falls back even when an earlier turn of the same
+provider and model had an endpoint.
+
+`tps`/`wall`/`stream` are produced tokens per streaming second / request to
+completed step / request to the last chunk. The sidebar's rate (per turn, and
+the session average on its totals) is the **weighted** one — produced tokens
+divided by the summed streaming windows — so it answers "how fast did this
+produce"; the `latency` view reports the p50 of the per-step rates instead, which
+answers "how fast is a typical step". A change of identity is not by
+itself a fault — a gateway may re-route deliberately — so `affinity` pairs the
+count with the cache reuse it actually cost. The panel's `?` overlay defines
+every number in place.
+
+## Configuration
+
+Options apply to both entries (each side reads the ones it needs):
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | `false` disables that side completely — no line, no panel, no recording. |
+| `db` | per-OS state path | SQLite path override. Must match between the server and TUI entries. |
+| `turnTotals` | `"latest"` | How the turn segment counts prompt usage: `latest` shows the prompt size the turn ended with; `sum` adds every step of the turn. |
+| `sidebar` | `true` | Show the session summary and the per-prompt history — cache hit and cost per turn — in the session sidebar (the slot is invisible while the sidebar is hidden). |
+| `sidebarTurns` | `5` | How many turns the sidebar history shows. |
+| `panel` | `true` | Show the `/usage` statistics panel and its command. `false` keeps the line and the sidebar. |
+| `identity` | `"endpoint"` | Which identity the line leads with: `endpoint` shows the endpoint that served the turn (falling back to `provider/model`); `model` always shows `provider/model#variant`. |
+| `fields` | see below | Toggle line segments. |
+| `labels` | see below | Override line labels (the plugin is English-only by default). |
+
+### Fields and labels
+
+```jsonc
+{
+  "options": {
+    "fields": { "clock": true, "delta": true, "model": true, "variant": true, "turn": true, "session": true, "reasoning": false, "cost": false, "cacheExpiry": true },
+    "turnTotals": "latest",
+    "labels": { "delta": "Δ", "turn": "", "session": "sess", "step": "step", "steps": "steps", "input": "in", "cached": "cached", "output": "out", "reasoning": "reason", "cost": "cost", "cacheExpired": "cache expired", "providerChanged": "changed", "modelChanged": "model changed" }
+  }
+}
+```
+
+`fields: { "clock": false, "delta": false, "session": false }` turns the line
+into a pure `provider/model · turn …` reading.
+
+## Database and privacy
+
+The recorder writes to the per-user state directory:
+
+| OS | Path |
+| --- | --- |
+| Linux / other | `$XDG_STATE_HOME/opencode/opencode-usage-insights/usage.db` (default `~/.local/state/opencode/opencode-usage-insights/usage.db`) |
+| macOS | `~/Library/Application Support/opencode/opencode-usage-insights/usage.db` |
+| Windows | `%LOCALAPPDATA%\opencode\opencode-usage-insights\usage.db` |
+
+`OPENCODE_USAGE_INSIGHTS_DB=/path/to/usage.db` overrides the path, and the `db`
+option overrides both. The file is private to the user: its directory is created
+`0700` and the file `0600` (POSIX), re-applied on every open. The TUI reads
+through a read-only connection, so it can never write, migrate or take the
+recorder's lock.
+
+Per step the database holds tokens, cost, timings, finish reason, the
+provider/model it ran as, the endpoint label, and the session title and working
+directory. **Prompts and responses are not stored**, and nothing leaves the
+machine. The schema, the indexes, the endpoint-discovery rules and the security
+notes live in [docs/internals.md](docs/internals.md).
+
+## CLI report
+
+From a checkout, the database can be read without opening the TUI:
+
+```sh
+bun run report                          # overview over all time
+bun run report models 7d                # one view, one range
+bun run report all                      # every view
+bun run report endpoints --model deepseek-v4.1-flash-free
+bun run report periods --granularity month
+bun run report affinity --endpoint orcarouter-dsv4.1flash
+bun run report --json                   # raw rows and every analysis, for scripting
+bun run report --ndjson > backup.jsonl  # export the whole database
+bun run report --import backup.jsonl    # merge an export (idempotent)
+bun run report --help
+```
+
+The views come from the same `buildPanel` the TUI renders, so the terminal and
+the panel never drift apart. `--width`, `--granularity`, `--model`,
+`--endpoint`, `--sort` and `--asc` mirror what the panel's keys do.
+
+## Development
+
+```sh
+bun install
+bun run typecheck    # tsc --noEmit, strict
+bun test             # pure logic + database + TUI harness + render tests
+bun run build        # dist/index.js, dist/tui.js and declarations
+bun run demo         # print the line and every view from a seeded database
+bun run docs:images  # re-render docs/images/*.png (needs ImageMagick)
+```
+
+- `src/core.ts`, `src/line.ts`, `src/panel-data.ts` and `src/stats/` are pure:
+  turn accounting, the host-shape adapter, the view models, and the database,
+  queries and analysis layer. No host imports, so they are unit-testable without
+  a TUI runtime.
+- `src/endpoint.ts`, `src/text.ts` — endpoint discovery and text hygiene.
+- `src/recorder.ts` — the event-stream state machine that fills the database.
+- `src/panel-build.ts`, `src/panel.tsx`, `src/sidebar.tsx` — panel assembly, the
+  panel component, and the sidebar contribution.
+- `src/index.ts`, `src/tui.tsx` — the server and TUI entries.
+- `scripts/` — the demo, report, bench, platform-check and documentation-image
+  CLIs, plus the two-entry `Bun.build`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules and review
+expectations, and [docs/internals.md](docs/internals.md) for the database
+design, performance rules and how the TUI side is tested.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Author: Hugo Batista
+(<https://github.com/hugobatista>).

package/dist/core.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Pure turn accounting shared by the TUI line, the server recorder and the
+ * stats engine.
+ *
+ * Everything here operates on structural shapes that mirror the session
+ * messages published by OpenCode, so the logic stays testable without a host
+ * runtime and without the effect-based schema types.
+ */
+export type ModelRefLike = {
+    providerID: string;
+    id: string;
+    variant?: string | undefined;
+};
+export type AssistantMessage = {
+    type: "assistant";
+    id: string;
+    time?: {
+        created?: number | undefined;
+        streamed?: number | undefined;
+        completed?: number | undefined;
+    } | undefined;
+    model?: ModelRefLike | undefined;
+    tokens?: {
+        input?: number | undefined;
+        output?: number | undefined;
+        reasoning?: number | undefined;
+        cache?: {
+            read?: number | undefined;
+            write?: number | undefined;
+        } | undefined;
+    } | undefined;
+    cost?: number | undefined;
+    finish?: string | null | undefined;
+    rawFinish?: string | null | undefined;
+};
+export type PromptMessage = {
+    type: "user" | "synthetic" | "system";
+    id?: string | undefined;
+    time?: {
+        created?: number | undefined;
+    } | undefined;
+};
+export type TranscriptMessage = AssistantMessage | PromptMessage | {
+    type: string;
+    id?: string | undefined;
+    time?: {
+        created?: number | undefined;
+    } | undefined;
+};
+/** Accumulated token usage for a group of assistant steps. */
+export type Totals = {
+    input: number;
+    cached: number;
+    output: number;
+    reasoning: number;
+    cacheWrite: number;
+    cost: number;
+    steps: number;
+};
+export type CacheDrop = {
+    messageID: string;
+    /** Tokens that were expected to hit the prompt cache but did not. */
+    tokens: number;
+    /** `cache.read` of the step that was used as the reuse reference. */
+    prevCached: number;
+    /** Time between the reference step's completion and this step's request. */
+    gapMs: number | undefined;
+};
+export type TurnStats = {
+    /** Wall clock time of the last step's completion. */
+    endAt: number | undefined;
+    /** Creation time of the first settled step of the turn. */
+    startAt: number | undefined;
+    /** Creation time of the prompt that opened this turn. */
+    promptAt: number | undefined;
+    /** Time between the previous prompt and this turn's prompt. */
+    promptGapMs: number | undefined;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    /** Gateway routing endpoint that served the turn, when a source identifies it. */
+    router: string | undefined;
+    /**
+     * The displayed identity differs from the previous turn's. The TUI fills it
+     * in (the transcript carries no routing information); the line warns with the
+     * same `changed` marker it uses for a provider switch.
+     */
+    identityChanged: boolean;
+    affinityKey: string | undefined;
+    /** Provider ID differs from the previous turn in the same transcript. */
+    providerChanged: boolean;
+    /** Provider is the same but the model or variant differs. */
+    modelChanged: boolean;
+    totals: Totals;
+    /** Passed through from the caller (session-wide accumulated usage). */
+    session: Totals | undefined;
+    /**
+     * Prompt-side usage of the last finished step: the context the turn ended
+     * with. Summing `input`/`cached` over the steps of a turn counts the same
+     * re-sent prompt once per step, which is not what a context view means.
+     */
+    latest: Totals;
+    drops: CacheDrop[];
+    cacheDropTokens: number;
+    cacheExpired: boolean;
+    /** Assistant steps in the turn. */
+    steps: number;
+    /**
+     * Message ids of the settled steps of the turn, oldest first. The TUI looks
+     * up the endpoint the recorder stored for these steps, so the line reports
+     * who served *this* turn: a lookup by provider and model alone would tag a
+     * turn with the endpoint of an older one.
+     */
+    stepIDs: string[];
+};
+export type TurnSegment = {
+    assistants: AssistantMessage[];
+    prompt: TranscriptMessage | undefined;
+};
+/** Message types that open a turn: a run of assistants belongs to the last one. */
+export declare const PROMPT_BOUNDARIES: ReadonlySet<string>;
+/**
+ * Split a transcript into turns. A turn is a run of assistant steps opened by
+ * a prompt boundary (`user`, `synthetic`, `system`). Idle notices, info
+ * messages, compactions and shell entries keep the current turn open so a
+ * single execution is never split in two.
+ */
+export declare function transcriptSegments(messages: readonly TranscriptMessage[]): TurnSegment[];
+/**
+ * The last `count` segments, found by walking the transcript backwards. The
+ * live line only needs the turn that just ended and the one before it, and a
+ * long session holds tens of thousands of messages: the tail walk stops as
+ * soon as it has them, instead of building a segment for every turn.
+ */
+export declare function transcriptTail(messages: readonly TranscriptMessage[], count: number): TurnSegment[];
+export declare function tokenCounts(message: AssistantMessage): {
+    input: number;
+    output: number;
+    reasoning: number;
+    read: number;
+    write: number;
+};
+export declare function totalize(steps: readonly AssistantMessage[]): Totals;
+export declare function affinityKey(model: ModelRefLike | undefined): string | undefined;
+export declare function cacheRead(message: AssistantMessage | undefined): number;
+export declare function stepCreated(message: AssistantMessage | undefined): number | undefined;
+export declare function stepEnd(message: AssistantMessage | undefined): number | undefined;
+/**
+ * Cache reuse loss against a reference step, mirroring OpenCode's own
+ * `turn-usage` heuristic: only comparable when the model is identical, and
+ * OpenAI's endpoint reports small reads that are not worth flagging.
+ */
+export declare function cacheDrop(reference: AssistantMessage | undefined, current: AssistantMessage): number | undefined;
+/** Milliseconds between a reference step's completion and the next request. */
+export declare function stepGap(reference: AssistantMessage | undefined, current: AssistantMessage): number | undefined;
+/**
+ * Streaming duration of a step: request start to the last streamed chunk. The
+ * host's `streamed` stamp marks the end of streaming, so this is the window a
+ * generation rate belongs to — not a time to first token, which the session
+ * messages do not record.
+ */
+export declare function stepStreamMs(message: AssistantMessage): number | undefined;
+/**
+ * Tokens produced per second over a window. For a step the window is the
+ * streaming one: request start to the last streamed chunk (`created` →
+ * `streamed`) — `completed` marks the end of the step, which for a tool-call
+ * step happens after the tool calls were handled. Returns undefined when the
+ * window or the produced tokens are unknown. Single definition, shared by the
+ * recorder (which stores it per step) and the latency view.
+ */
+export declare function tokensPerSecond(produced: number, from: number | undefined, to: number | undefined): number | undefined;
+/** Output-plus-reasoning tokens per second of a step. */
+export declare function stepTps(message: AssistantMessage): number | undefined;
+/**
+ * True when a step has final numbers. A step that is still streaming reports
+ * partial tokens (usually zero) and no cache read yet, so reading it would
+ * render an empty line and invent a cache-expiry warning against it.
+ */
+export declare function isSettledStep(message: AssistantMessage): boolean;
+/**
+ * Compute the stats of the most recent turn in a transcript, including the
+ * comparison against the previous turn (affinity and cache reuse).
+ *
+ * Returns undefined while the newest turn is still being generated: the line
+ * appears when a turn ends, never with the zeroes of an in-flight response.
+ */
+export declare function computeTurn(messages: readonly TranscriptMessage[], session?: Totals): TurnStats | undefined;
+/** True when a cache drop is small enough to be endpoint noise. */
+export declare function isNoiseDrop(providerID: string | undefined, drop: number): boolean;
+export type LineTone = "base" | "muted" | "warning";
+export type LineSegment = {
+    text: string;
+    tone: LineTone;
+};
+export type LineLabels = {
+    delta: string;
+    turn: string;
+    session: string;
+    step: string;
+    steps: string;
+    input: string;
+    cached: string;
+    output: string;
+    reasoning: string;
+    cost: string;
+    cacheExpired: string;
+    providerChanged: string;
+    modelChanged: string;
+};
+/**
+ * How the turn segment counts prompt usage. `latest` shows the prompt size the
+ * turn ended with — the context view, and what OpenCode's own turn-token debug
+ * line reports. `sum` adds every step of the turn: the billing view, where a
+ * tool-call loop re-sends (and re-reads) the same context once per step.
+ */
+export type TurnTotalsView = "latest" | "sum";
+/**
+ * Which identity the line leads with. `endpoint` shows the gateway endpoint
+ * that served the turn (`orcarouter-dsv4.1flash`) when a recorder learned one,
+ * falling back to `provider/model`; `model` always shows `provider/model`.
+ * The same provider and model can be routed to different endpoints per request,
+ * so the endpoint is the identity a change is measured against.
+ */
+export type LineIdentity = "endpoint" | "model";
+export type LineFields = {
+    clock: boolean;
+    delta: boolean;
+    model: boolean;
+    variant: boolean;
+    turn: boolean;
+    session: boolean;
+    reasoning: boolean;
+    cost: boolean;
+    cacheExpiry: boolean;
+};
+export declare const DEFAULT_LABELS: LineLabels;
+export declare const DEFAULT_FIELDS: LineFields;
+export declare function formatClock(ms: number): string;
+export declare function formatDuration(ms: number): string;
+export declare function formatTokens(value: number): string;
+export declare function formatCost(value: number): string;
+/**
+ * The buckets the line displays, derived from a totals group. `input` is the
+ * *uncached* part of the prompt (fresh input plus cache writes, i.e. what the
+ * debug line's `new` counts on the prompt side), `prompt` is the whole prompt
+ * of the request and `output` is everything the model generated (visible output
+ * + reasoning). OpenCode's own debug line reconciles with these:
+ * `new = in + out` and `total = prompt + out`, with `prompt = in + cached`.
+ * The stored buckets stay raw; only the display folds.
+ */
+export type DisplayTotals = Totals & {
+    /** Whole prompt of the request: fresh input + cached reads + cache writes. */
+    prompt: number;
+};
+export declare function displayTotals(totals: Totals): DisplayTotals;
+/**
+ * Render the telemetry line as toned segments. The caller maps tones onto
+ * theme colors; `formatLine` joins the segments as plain text.
+ */
+export declare function formatLineSegments(stats: TurnStats, options?: {
+    labels?: Partial<LineLabels>;
+    fields?: Partial<LineFields>;
+    turnTotals?: TurnTotalsView;
+    identity?: LineIdentity;
+}): LineSegment[];
+export declare function formatLine(stats: TurnStats, options?: {
+    labels?: Partial<LineLabels>;
+    fields?: Partial<LineFields>;
+    turnTotals?: TurnTotalsView;
+    identity?: LineIdentity;
+}): string;

package/dist/endpoint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Endpoint discovery.
+ *
+ * OpenCode routes a model through a provider, and the endpoint the request was
+ * actually sent to is the identity that answers "who ran this inference": a
+ * gateway names its own routing endpoint in the response headers, and a
+ * per-operator provider is named by the host of its API. The recorder stores
+ * that endpoint on the step and nothing else about the route — the operator a
+ * header happens to mention is not the endpoint, so it is not kept.
+ *
+ * Everything here is pure so the discovery can be tested without a network
+ * stack.
+ */
+/** Header a gateway sets to name the routing endpoint that served the request. */
+export declare const ENDPOINT_HEADER: "x-opencode-endpoint-id";
+/** Longest endpoint id kept: a routing label, not a sentence. */
+export declare const ENDPOINT_MAX = 64;
+export type EndpointInfo = {
+    /** Routing endpoint or host that served the request. */
+    router?: string | undefined;
+    /** Where the finding came from: `header:<name>` or `endpoint:<host>`. */
+    source?: string | undefined;
+};
+/**
+ * Endpoint the gateway named in the response headers, when it named one.
+ *
+ * The value is a routing label, so it is validated as a token and lowercased:
+ * a gateway that changes the case between responses would otherwise read as a
+ * different endpoint and split its own history in two. Anything that is not a
+ * token (control characters, spaces, an essay) is not an endpoint id.
+ */
+export declare function inferFromHeaders(headers: Headers | Record<string, string | undefined> | undefined): EndpointInfo | undefined;
+/**
+ * True when `host` is `suffix`, a subdomain of it (`cdn.opencode.ai`), or a
+ * regional host that carries it as a label tail (`us-central1-aiplatform.googleapis.com`).
+ * The boundary has to fall on a dot or a dash: a host that merely contains a
+ * known domain (`api.anthropic.com.evil.tld`) names nothing.
+ *
+ * A `*` in the pattern stands for one label, for the hosts whose region sits
+ * in the middle (`bedrock-runtime.*.amazonaws.com`).
+ */
+export declare function hostMatches(host: string, pattern: string): boolean;
+/** Endpoint named by the host of the request URL. */
+export declare function inferFromUrl(url: string | undefined): EndpointInfo | undefined;
+/** First candidate that named an endpoint, headers before the URL. */
+export declare function mergeEndpoint(...candidates: readonly (EndpointInfo | undefined)[]): EndpointInfo | undefined;