Compaction: Provider options flow and accurate usage accounting

[riatzukiza]

Epic: #46

Summary

Ensure provider options and accurate usage accounting flow through compaction to prevent miscount and API errors.

Problem

• Past reports show missing providerOptions in compaction path (BUG: @ai-sdk/openai 2.0.50 breaks OpenAI OAuth plugin requiring store: false (missing providerOptions in compaction) anomalyco/opencode#3118) and need for includeUsage (I can not configure the limit for litellm anomalyco/opencode#2787) for accurate tokens/cost.

Proposal

• Audit compaction streamText options: headers, providerOptions, includeUsage forwarding.
• Verify usage reporting on finish-step matches regular prompt path.

Code Refs

• packages/opencode/src/session/compaction.ts:147-179 (streamText options)
• packages/opencode/src/session/compaction.ts:211-220 (usage aggregation)
• packages/opencode/src/provider/transform.ts (ProviderTransform.providerOptions)

Tasks

• Add tests for usage accounting consistency in compaction
• Ensure includeUsage=true where applicable
• Cross-check headers/options equality with prompt path

Acceptance Criteria

• Usage tokens/cost in compaction match those from equivalent non-compaction flows.
• No API errors due to missing options.

[riatzukiza]

Related Issues & Context

This Provider Options and Usage Accounting issue has important technical relationships:

Direct Impact:

• Compaction: Pruning/soft compaction and selective tool-output deletion #50 - Pruning: Usage tracking needed to measure pruning effectiveness (tokens saved vs cost of compaction)
• Compaction: Structured BUILD-mode handoff summary prompt #49 - Structured Handoff: Handoff generation is token-intensive - need accurate cost tracking
• Compaction: Configurable preserved turns and prune thresholds #55 - Configurable Options: Usage accounting helps users tune thresholds for optimal cost/performance

Cost Management:

• Compaction: Telemetry and /status for context + decisions #52 - Telemetry: Usage accounting provides the raw data for telemetry dashboards and cost breakdowns
• Epic: Compaction Update #46 - Compaction Update Epic: This is critical for the overall cost management goals of the epic

Strategic Importance:

• Epic: Subagent State Handoff & Context Boundary Resilience #56 - Subagent State Handoff: Usage accounting becomes essential for subagent cost tracking. Subagents have separate token usage that needs to be:
  • Tracked individually (subagent session costs)
  • Attributed to parent sessions (total cost accounting)
  • Compared across context transfer strategies

Technical Dependencies:

• Compaction: Tests – boundary, rules, pruning, integration #54 - Tests: Usage accounting consistency is a critical test case to prevent cost surprises
• Compaction: Concurrency/locking robustness and retries #53 - Concurrency: Usage tracking must be accurate under concurrent compaction operations

Implementation Impact:

This issue fixes the "silent cost increase" problem where:

1. Compaction operations might use different provider options
2. Usage reporting might be incomplete or inaccurate
3. Users see unexpected token/cost increases

Business Impact:

Accurate usage accounting is CRITICAL for:

• Cost transparency - users understanding compaction costs
• ROI calculation - is compaction saving more tokens than it costs?
• Subagent budgeting - understanding true cost of subagent delegation

Without reliable usage accounting, both compaction and subagent features become opaque cost centers that users can't trust or optimize.