Expose native OpenCode chat usage snapshots and replay session metrics

Read V2 session accounting, latest assistant prompt/cache components and native request-to-stream boundary. Resolve capacity by location/provider/catalog id with bounded metadata caching. Coalesce active/final readbacks; retain message-less session snapshots without changing admission or compaction state.

Provenance: https://opencode.ai/v2/openapi.json and anomalyco/opencode V2 4617210822bdbb31e5749751afbfb4584ccedac8: packages/schema/src/token-usage.ts, session-event.ts; packages/core/src/session/usage.ts, projector.ts, message-updater.ts, runner/step.ts. Native output is visible output, reasoning separate. Session totals include all five non-overlapping components. Generation rate uses created-to-streamed, not tool-inclusive completion.

Limitations: metrics remain unknown for missing components, absent timing/model metadata, reads beyond bounded latest-message/catalog budgets, or context preceding compaction. No local pricing, token estimation or default capacity. V1 gets no invented cumulative metrics; older V2 events remain available when readback is unavailable. No deployment or protocol/web/docs changes.

Checks: go test ./...; focused usage/stream race tests; go vet ./internal/opencode ./internal/server; go build ./...; git diff --check.
This commit is contained in:
2026-10-21 00:12:25 +01:00
parent 83b60990d2
commit ce3482b057
10 changed files with 733 additions and 15 deletions
+112 -10
View File
@@ -42,7 +42,9 @@ type Chat struct {
// operation and status on the shared connection, so two calls must not
// overlap; the permission poller runs alongside the read loop's
// prompt/interrupt/reply calls.
mu sync.Mutex
mu sync.Mutex
usageMu sync.Mutex
usageModels map[string]usageModelCache
}
// NewChat brokers chat for one owned OpenCode endpoint. The connection must be
@@ -757,6 +759,8 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
ctx, cancel := context.WithCancel(ctx)
defer cancel()
var delivery sync.Mutex
usageReadbackAvailable := false // protected by delivery, fallback for older API builds
var pendingUsage *protocol.ChatUsage // latest cumulative event, never a sum
state.mu.Lock()
busy := state.Active
state.mu.Unlock()
@@ -764,12 +768,28 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
busy = value
state.mu.Lock()
state.Active = value
state.usageDirty = true
if !value {
state.Compaction = nil
}
state.mu.Unlock()
}
deliver := func(frame protocol.ChatEventFrame) error {
// Native usage is cumulative but lacks context/model/timing. Coalesce it
// into one complete readback; never erase richer metrics with a partial
// usage event or issue HTTP reads for every token delta.
if frame.Kind == protocol.ChatEventUsage {
state.mu.Lock()
state.usageDirty = true
state.mu.Unlock()
delivery.Lock()
defer delivery.Unlock()
if usageReadbackAvailable {
pendingUsage = frame.Usage
return nil
}
return emit(frame)
}
delivery.Lock()
defer delivery.Unlock()
if frame.Kind == protocol.ChatEventStep || frame.Kind == protocol.ChatEventText || frame.Kind == protocol.ChatEventTool || frame.Kind == protocol.ChatEventReasoning || (frame.Compaction != nil && frame.Compaction.Status == "running") {
@@ -829,10 +849,81 @@ func (c *Chat) Stream(ctx context.Context, id string, ready func(), emit func(pr
}
}()
defer func() { cancel(); <-watchDone }()
usageRefreshGate := make(chan struct{}, 1)
refreshUsage := func() error {
if c.conn.Backend == "v1" {
return nil
}
select {
case usageRefreshGate <- struct{}{}:
defer func() { <-usageRefreshGate }()
default:
return nil
}
readCtx, readCancel := context.WithTimeout(ctx, 5*time.Second)
usage, err := c.Usage(readCtx, id)
readCancel()
if err != nil {
// A failed enrichment read must not lose authoritative native totals.
delivery.Lock()
defer delivery.Unlock()
usageReadbackAvailable = false
if pendingUsage != nil {
usage := pendingUsage
pendingUsage = nil
return emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage})
}
return nil // unavailable metrics must not break chat
}
delivery.Lock()
defer delivery.Unlock()
usageReadbackAvailable = true
pendingUsage = nil
return emit(protocol.ChatEventFrame{SessionID: id, Kind: protocol.ChatEventUsage, Usage: usage})
}
if err := refreshUsage(); err != nil {
return err
}
usageDone := make(chan struct{})
go func() {
defer close(usageDone)
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
}
state.mu.Lock()
refresh := state.usageDirty || state.Active
state.usageDirty = false
state.mu.Unlock()
if refresh {
if err := refreshUsage(); err != nil {
cancel()
_ = body.Close()
return
}
}
}
}()
defer func() { cancel(); <-usageDone }()
if ready != nil {
ready()
}
return c.scanChatEventsWithState(ctx, body, id, state, deliver)
err = c.scanChatEventsWithState(ctx, body, id, state, deliver)
if ctx.Err() == nil {
state.mu.Lock()
dirty := state.usageDirty
state.mu.Unlock()
if dirty {
if refreshErr := refreshUsage(); refreshErr != nil {
return refreshErr
}
}
}
return err
}
// scanChatEvents turns an SSE body into protocol frames, one bounded frame at a
@@ -859,6 +950,20 @@ func (c *Chat) scanChatEventsWithState(ctx context.Context, body io.Reader, sess
if len(payload) == 0 {
continue
}
var usageTrigger struct {
Type string `json:"type"`
Data struct {
SessionID string `json:"sessionID"`
} `json:"data"`
}
if json.Unmarshal(payload, &usageTrigger) == nil && usageTrigger.Data.SessionID == sessionID {
switch usageTrigger.Type {
case "session.usage.updated", "session.step.ended", "session.step.failed", "session.compaction.ended", "session.compaction.failed", "session.model.selected", "session.moved", "session.execution.succeeded", "session.execution.failed", "session.execution.interrupted":
state.mu.Lock()
state.usageDirty = true
state.mu.Unlock()
}
}
frame, ok, err := NormalizeChatEvent(payload, sessionID, state)
if err != nil {
return err
@@ -1056,6 +1161,7 @@ type ChatStreamState struct {
Forms map[string]string
readGate chan struct{}
readback *ShellSnapshot
usageDirty bool
}
func (s *ChatStreamState) lastMessageID() string {
@@ -1206,9 +1312,9 @@ func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamStat
if messageID == "" && stream != nil {
messageID = stream.lastMessageID()
}
// Every pushed frame must carry a stable message id so the client can
// attribute it; without one this is not a chat frame.
if messageID == "" {
// Usage is session state; native V2 UsageUpdated has no message id. Other
// message frames still require a stable id for transcript attribution.
if messageID == "" && outer.Type != "session.usage.updated" {
return protocol.ChatEventFrame{}, false, nil
}
frame := protocol.ChatEventFrame{SessionID: sessionID, MessageID: messageID}
@@ -1234,11 +1340,7 @@ func NormalizeChatEvent(payload []byte, sessionID string, stream *ChatStreamStat
frame.Part = &protocol.ChatPart{Type: protocol.ChatPartTool, ID: data.ID, Name: data.Name, State: state}
case outer.Type == "session.usage.updated":
frame.Kind = protocol.ChatEventUsage
input, output := data.InputTokens, data.OutputTokens
if data.Tokens.Input != 0 || data.Tokens.Output != 0 {
input, output = data.Tokens.Input, data.Tokens.Output
}
frame.Usage = &protocol.ChatUsage{InputTokens: input, OutputTokens: output, Cost: data.Cost}
frame.Usage = decodeUsageSnapshot(outer.Data)
default:
return protocol.ChatEventFrame{}, false, nil
}