Token Usage Tracker Middleware

[veeqtoh]

Is your middleware request related to a problem? Please describe.

There is no built-in way to track token consumption per agent, per user, or per request within the Intercept middleware stack. Teams currently rely on provider dashboards or external packages, which breaks the unified middleware mental model.

Proposed solution

A pass-through middleware that extracts token usage metadata from the provider response and persists it for analytics and alerting.

API Design

public function middleware(): array
{
    return [
        new TokenUsageTracker(
            trackInput: true,
            trackOutput: true,
            trackTotal: true,
            onThreshold: function (Usage $usage) {
                if ($usage->total > 4000) {
                    Log::warning('High token usage', ['usage' => $usage]);
                }
            }
        ),
    ];
}

Data captured

• prompt tokens
• completion tokens
• total tokens
• model (e.g., gpt-4o)
• agent class name
• user id
• session id

Storage

Write to a dedicated intercept_token_usage table or/and emit a Laravel event (TokenUsageRecorded) so users can wire their own pipelines (e.g., to Prometheus, InfluxDB, or Laravel Pulse).

Describe the middleware's supported actions you'd like

• log
• maybe send email

Additional context

Sudden spikes can indicate injection loops or runaway tool calls.