Token usage: no stable machine-readable export and no turn boundaries for external consumers #60278

Summary

OpenCode tracks token usage per assistant message and per session, but exposes
no stable, documented way to consume that data outside the TUI. External
consumers (scripts, CI, cost dashboards, agent tooling) are forced to
reverse-engineer the internal SQLite store, including WAL side files.

Current gaps

1. No machine-readable export. Usage lives in session_v2.tokens_* and
   session_message.data (JSON-in-TEXT) inside ~/.local/share/opencode/opencode.db.
   There is no CLI command or documented API to export per-session /
   per-message usage as JSON/Markdown.

2. No turn or invocation boundary. Sessions have no turn_id or
   task-boundary event. A long-lived or reused session cannot be split into
   separate invocations, so usage from earlier work bleeds into later reports.

3. No per-response identity beyond message.id. There is no response-level
   id comparable to other hosts, which limits dedup and cross-checking.

4. Effort is a model variant, not reasoning effort. model.variant
   (default/low/high) is the only signal; there is no reasoning-effort
   field, so consumers cannot distinguish effort levels reliably.

5. Schema is internal and versioned. session vs session_v2,
   message vs session_message, JSON-in-TEXT columns. Any rename breaks
   parsers, and the DB is live with WAL files, requiring snapshot copying.

Requested improvement

Please consider adding a stable, documented way to obtain per-session and
per-message token usage:

• a CLI command such as opencode usage export --session <id> --format json
  (or extending opencode stats) emitting per-message records with
  session_id, parent_session_id, agent, model, provider, variant,
  tokens { input, output, reasoning, cache { read, write } },
  time { created, completed };
• optional per-turn boundaries (a turn id or task-boundary event) so a reused
  session's usage can be attributed to the correct invocation;
• alternatively, document the SQLite schema as a supported read-only interface.

Why this matters

Token accounting is increasingly performed by external tooling, not only by the
TUI. A stable export would let consumers avoid coupling to OpenCode internals.
(Related but different in scope: #41915 requests an in-TUI /usage report.)

Environment

• OpenCode v2.0.27
• macOS, data dir ~/.local/share/opencode/