feat(usage): per-request token ledger and measured bucket capacity (2.5.0)

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.5.0] - 2026-10-31
+
+### Added
+
+- **Per-request token ledger.** Every streaming response appends one JSONL row with the account, model, variant and the backend `usageMetadata` counts (input, output, reasoning, cache read). `antigravity-usage.jsonl` lives next to the other plugin state and is append-only.
+- **Measured bucket capacity.** Each quota check records its percentages; pairing them with the ledger yields `TOKENS/1%`, `CALLS/1%` and the share of windows where the bucket actually moved. Measured on Argon: two 32k-token calls dropped the bucket 1.01 points, two 15k-token calls dropped it 0.00 points, so the report publishes both readings and labels the linear estimate as informational instead of asserting an allowance Google never publishes.
+- **`antigravity_usage` tool and `/antigravity-usage` command.** Consumption per account, per model and per day, plus the capacity table.
+
 ## [2.4.3] - 2026-10-31
 
 ### Fixed

dist/src/plugin/core/streaming/transformer.d.ts

@@ -1,4 +1,4 @@
-import type { SignatureStore, StreamingCallbacks, StreamingOptions, ThoughtBuffer } from './types';
+import type { TokenUsage, SignatureStore, StreamingCallbacks, StreamingOptions, ThoughtBuffer } from './types';
 export declare const CLEAN_GUARDRAIL_MESSAGE = "[Solicitud bloqueada por filtros de seguridad de Gemini. Por favor, intenta reformular tu prompt o enfoque.]";
 export declare const CLEAN_CLAUDE_SAFETY_MESSAGE = "[Respuesta bloqueada por el monitor de seguridad de Claude en esta cuenta. safety_level no interviene en modelos Claude: quita o reformula el contenido marcado (suele venir del contexto del proyecto o de AGENTS.md) o usa otro modelo.]";
 export declare const CLEAN_MALFORMED_CALL_MESSAGE = "[Llamada de herramienta vac\u00EDa o malformada generada por el modelo. Reintentando o reformula tu solicitud.]";
@@ -25,6 +25,8 @@ export declare function transformStreamingPayload(payload: string, transformThin
 export declare function deduplicateThinkingText(response: unknown, sentBuffer: ThoughtBuffer, displayedThinkingHashes?: Set<string>): unknown;
 export declare function transformSseLine(line: string, signatureStore: SignatureStore, thoughtBuffer: ThoughtBuffer, sentThinkingBuffer: ThoughtBuffer, callbacks: StreamingCallbacks, options: StreamingOptions, debugState: {
     injected: boolean;
+}, usageState?: {
+    value?: TokenUsage;
 }): string;
 export declare function cacheThinkingSignaturesFromResponse(response: unknown, signatureSessionKey: string, signatureStore: SignatureStore, thoughtBuffer: ThoughtBuffer, onCacheSignature?: (sessionKey: string, text: string, signature: string) => void): void;
 export declare function createStreamingTransformer(signatureStore: SignatureStore, callbacks: StreamingCallbacks, options?: StreamingOptions): TransformStream<Uint8Array, Uint8Array>;

dist/src/plugin/core/streaming/types.d.ts

@@ -13,10 +13,19 @@ export interface SafetyRating {
     probability: "NEGLIGIBLE" | "LOW" | "MEDIUM" | "HIGH" | string;
     blocked?: boolean;
 }
+export interface TokenUsage {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    thoughtsTokenCount?: number;
+    cachedContentTokenCount?: number;
+    totalTokenCount?: number;
+}
 export interface StreamingCallbacks {
     onCacheSignature?: (sessionKey: string, text: string, signature: string) => void;
     onInjectDebug?: (response: unknown, debugText: string) => unknown;
     onSafetyRatings?: (ratings: SafetyRating[]) => void;
+    /** Final token usage for the response, reported once the stream flushes. */
+    onUsage?: (usage: TokenUsage) => void;
     transformThinkingParts?: (parts: unknown) => unknown;
 }
 export interface StreamingOptions {