How Cost Tracking Works for Voice Control Sessions in God’s Eye View

Cost tracking for voice control sessions in God’s Eye View relies on a three-tier architecture: a model registry with USD-per-million-token rates, configurable spend-guard limits, and a stateful session tracker that converts OpenAI Realtime API usage into running dollar amounts with soft warnings and hard caps.

God’s Eye View implements defensive cost accounting to prevent runaway spending during voice-controlled AI sessions. The system intercepts every response.done event from the OpenAI Realtime API, converts token usage into precise USD costs, and enforces tier-specific limits that trigger UI alerts or automatic session termination. This implementation spans src/voice/voiceCost.js for rate calculations and src/voice/gevRealtime.js for session orchestration.

Voice Cost Architecture

The cost tracking system combines three tightly coupled components to provide real-time spend visibility and protection.

Model Registry and Pricing

The VOICE_MODELS constant in src/voice/voiceCost.js (lines 49-66) defines the available OpenAI Realtime tiers—standard and mini—along with their USD-per-million-token rates for text, audio, and cached inputs. This registry serves as the authoritative price list for all cost calculations.

Spend-Guard Limits

The VOICE_COST_LIMITS object (lines 70-73) establishes two thresholds: warnUsd for soft warnings and capUsd for hard termination. These limits are passed into every tracker instance and evaluated against the running total after each API response.

Session Cost Tracker

The createVoiceCostTracker factory function (lines 124-141) implements a state machine that accumulates usage, latches threshold states, and exposes a snapshot for UI rendering. Each voice session receives its own tracker instance bound to the specific model ID being consumed.

Token-to-USD Conversion Pipeline

When the Realtime API returns a response.done event, the system extracts the usage object and processes it through a multi-stage pipeline.

Splitting Token Categories

The splitUsageTokens function (lines 248-285) categorizes usage into billable buckets: text versus audio versus image, and cached versus uncached inputs. This granular separation ensures that each token type is priced according to its specific rate from the VOICE_MODELS registry.

Calculating Dollar Amounts

The estimateUsageCostUsd function (lines 222-236) multiplies each token bucket by its corresponding rate and divides by 1,000,000 to produce the final USD value. This calculation runs for every API response, producing micro-charges that accumulate into the session total.

Session Lifecycle Integration

Cost tracking begins before the first API call and adapts dynamically as the session configuration resolves.

Provisional Tracker Creation

When gevRealtime.start() initializes a session, it creates a provisional tracker using the tier selected by the user (lines 60-66). This placeholder displays "$0.00" while the application fetches the actual model configuration from the token endpoint.

Rebinding to the Actual Model

Once the OpenAI token response arrives, the code replaces the provisional tracker with one bound to the real modelId (lines 80-87). This defensive step ensures accurate pricing even when environment overrides map tiers to different underlying models than expected.

Recording Usage Events

Inside handleRealtimeEvent, every response.done triggers costTracker.record() (lines 254-262). This method:

1. Converts the usage object to USD via the pipeline described above.
2. Adds the amount to the running total.
3. Checks against warnUsd and capUsd thresholds.
4. Returns a state object indicating whether thresholds were crossed.

Threshold Enforcement and UI Feedback

The tracker communicates session health through a reactive UI binding that updates after every recorded response.

State Level Transitions

The tracker maintains three levels: ok, warn, and cap. When the running total crosses warnUsd, the tracker sets warned: true and emits a one-time UI warning. If the total reaches capUsd, the tracker sets capped: true, marks the session as ending, and triggers automatic termination via stop().

DOM Synchronization

The syncCostUi method (implied in the event handling at lines 254-262) writes the formatted cost string (e.g., ~$0.42) into the #gev-voice-cost-value element and updates the data-level attribute to enable CSS styling for the current threshold state.

Error Handling and Edge Cases

The system includes defensive mechanisms for incomplete data and configuration drift.

Incomplete Session Handling

If a connection closes before the final response.done event arrives, the markIncomplete() method tags the snapshot with an asterisk (e.g., ~$0.42*) to indicate that the displayed cost may under-represent actual usage.

Unknown Model Fallback

When the server returns a model ID not present in VOICE_MODELS, the code falls back to the most expensive known tier to prevent under-metering (lines 84-95). It simultaneously logs a developer warning to highlight the configuration mismatch.

Implementation Examples

Creating a Provisional Tracker

// Inside gevRealtime.start() - using selected tier before token fetch
this.costTracker = createVoiceCostTracker({
  tier: this.voiceTier,
  limits: this.voiceLimits,
});

Rebinding After Token Resolution

// After token endpoint returns actual model ID
this.costTracker = createVoiceCostTracker({
  modelId: minted.model || resolveVoiceModel(this.voiceTier).id,
  limits: this.voiceLimits,
});

Recording Realtime Usage

// Inside handleRealtimeEvent on response.done
const costState = this.costTracker.record(payload.response.usage);

if (costState.warnCrossed) {
  console.warn(`Voice cost warning: ${costState.display}`);
}

if (costState.capCrossed) {
  console.error(`Voice cost cap reached: ${costState.display}`);
  this.stop(); // Force immediate termination
}

Updating the Interface

syncCostUi() {
  const state = this.costTracker.state();
  const el = document.getElementById('gev-voice-cost-value');
  
  el.textContent = state.display;    // e.g., "~$0.42"
  el.dataset.level = state.level;    // "ok" | "warn" | "cap"
}

Summary

• Model registry: VOICE_MODELS in voiceCost.js defines OpenAI Realtime rates for standard and mini tiers.
• Spend guards: VOICE_COST_LIMITS provides configurable warnUsd and capUsd thresholds.
• State machine: createVoiceCostTracker accumulates costs, checks limits, and manages UI state transitions.
• Lifecycle binding: Trackers start as provisional instances keyed by tier, then rebind to actual modelId values after token fetching.
• Defensive pricing: Unknown models default to the most expensive tier; incomplete sessions display asterisk-marked estimates.

Frequently Asked Questions

How does God’s Eye View prevent unlimited spending during voice sessions?

The capUsd threshold in VOICE_COST_LIMITS acts as a hard ceiling. When costTracker.record() detects the running total has reached this limit, it sets capped: true, marks the session as ending, and automatically invokes stop() to terminate the connection. This mechanism prevents API calls from accumulating beyond the configured maximum.

What happens if the OpenAI model ID changes mid-session?

When the token endpoint returns a modelId that differs from the initial tier selection, gevRealtime.js (lines 80-87) creates a new tracker instance using the actual model ID. This ensures cost calculations use the correct rates from VOICE_MODELS rather than the originally requested tier, accounting for environment overrides or server-side model routing.

How are text and audio tokens priced differently?

The splitUsageTokens function (lines 248-285) separates usage into distinct categories including text and audio inputs/outputs. The estimateUsageCostUsd function then applies model-specific rates to each bucket—for example, audio tokens typically cost more than text tokens—before summing the partial costs into the final USD amount for that response.

What does the asterisk (*) indicate in the cost display?

The asterisk appears when markIncomplete() has been called, typically because the session disconnected before receiving a final usage object. This visual indicator warns users that the displayed dollar amount may be lower than the actual charges incurred, as unreported usage from the final request is not included in the total.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}