feat: propagate cache metrics through harness token usage (#14746)

## Summary

Propagate `cachedInputTokens` and `cacheCreationInputTokens` through the
Mastra harness token usage pipeline so downstream consumers (e.g.,
auggie-v2 print mode) can include cache hit/miss metrics in session
output.

## Problem

The AI SDK provider already extracts cache read tokens from the backend
(`cache_read_input_tokens` in TOKEN_USAGE nodes), and `normalizeUsage()`
makes `cachedInputTokens` available on the `LanguageModelUsage` type.
However, the harness `processStream()` step-finish handler only
extracted `promptTokens` and `completionTokens`, completely ignoring
cache fields. This meant cache metrics were stripped before reaching any
consumer.

## Changes

### `types.ts`
- Added `cachedInputTokens?: number` and `cacheCreationInputTokens?:
number` to `TokenUsage` interface
- Updated `defaultDisplayState()` to initialize cache fields to 0

### `harness.ts`
- Added `emptyTokenUsage()` helper for consistent zero-initialization
with all 5 fields
- Updated `processStream()` step-finish handler to extract
`cachedInputTokens` from usage
- Updated all 7 reset sites to use `emptyTokenUsage()`
- Updated `loadThreadMetadata()` to restore cache fields from saved
thread metadata
- Updated `getTokenUsage()` return type from inline 3-field type to
`TokenUsage`
- Updated `usage_update` event emission and display state handlers to
propagate cache fields

### `token-usage.test.ts`
- Added test: extracts `cachedInputTokens` from usage
- Added test: accumulates `cachedInputTokens` across multiple steps
- Added test: defaults cache fields to 0 when not present

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Token usage now includes cached-input and cache-creation-input token
metrics; these metrics are shown in the UI, included in persisted thread
metadata, emitted in lifecycle and streaming updates, and returned by
the public token-usage API.

* **Tests**
* Added tests ensuring cached token fields accumulate correctly across
streaming steps and default to zero when absent.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Tyler Barnes <tylerdbarnes@gmail.com>
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>

Author: 3 people

.changeset/cache-metrics-harness-token-usage.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Propagate cache metrics (`cachedInputTokens`, `cacheCreationInputTokens`) through harness token usage. The step-finish handler now extracts `cachedInputTokens` from AI SDK usage and propagates it through `usage_update` events, `getTokenUsage()`, display state, and thread metadata persistence.

packages/core/src/harness/display-state.test.ts

@@ -5,7 +5,7 @@ import { InMemoryStore } from '../storage/mock';
 import { ChunkFrom } from '../stream/types';
 import { Harness } from './harness';
 import type { HarnessEvent } from './types';
-import { defaultDisplayState } from './types';
+import { createEmptyTokenUsage, defaultDisplayState } from './types';
 
 function createHarness(storage?: InMemoryStore) {
   const agent = new Agent({
@@ -31,7 +31,7 @@ describe('defaultDisplayState', () => {
     const ds = defaultDisplayState();
     expect(ds.isRunning).toBe(false);
     expect(ds.currentMessage).toBeNull();
-    expect(ds.tokenUsage).toEqual({ promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+    expect(ds.tokenUsage).toEqual(createEmptyTokenUsage());
     expect(ds.activeTools).toBeInstanceOf(Map);
     expect(ds.activeTools.size).toBe(0);
     expect(ds.toolInputBuffers).toBeInstanceOf(Map);
@@ -71,7 +71,7 @@ describe('Harness.getDisplayState()', () => {
     const ds = harness.getDisplayState();
     expect(ds.isRunning).toBe(false);
     expect(ds.currentMessage).toBeNull();
-    expect(ds.tokenUsage).toEqual({ promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+    expect(ds.tokenUsage).toEqual(createEmptyTokenUsage());
     expect(ds.activeTools.size).toBe(0);
     expect(ds.pendingApproval).toBeNull();
     expect(ds.pendingQuestion).toBeNull();
@@ -1321,7 +1321,7 @@ describe('resetThreadDisplayState', () => {
     expect(harness.getDisplayState().tokenUsage.totalTokens).toBe(150);
 
     emit(harness, { type: 'thread_created', thread: { id: 'new', title: 'New' } } as any);
-    expect(harness.getDisplayState().tokenUsage).toEqual({ promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+    expect(harness.getDisplayState().tokenUsage).toEqual(createEmptyTokenUsage());
   });
 
   it('preserves isRunning across thread_created', () => {

packages/core/src/harness/harness.ts

@@ -33,7 +33,7 @@ import {
   taskWriteTool,
 } from './tools';
 import type { TaskItemSnapshot } from './tools';
-import { defaultDisplayState, defaultOMProgressState } from './types';
+import { createEmptyTokenUsage, defaultDisplayState, defaultOMProgressState } from './types';
 import type {
   AvailableModel,
   HeartbeatHandler,
@@ -57,10 +57,6 @@ import type {
   ToolCategory,
 } from './types';
 
-function createEmptyTokenUsage(): TokenUsage {
-  return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
-}
-
 function getUsageNumber(usage: Record<string, unknown>, key: string): number | undefined {
   const value = usage[key];
   if (typeof value === 'number' && Number.isFinite(value)) {
@@ -1057,6 +1053,8 @@ export class Harness<TState = {}> {
           promptTokens: savedUsage.promptTokens ?? 0,
           completionTokens: savedUsage.completionTokens ?? 0,
           totalTokens: savedUsage.totalTokens ?? 0,
+          cachedInputTokens: savedUsage.cachedInputTokens ?? 0,
+          cacheCreationInputTokens: savedUsage.cacheCreationInputTokens ?? 0,
         };
       } else {
         this.tokenUsage = createEmptyTokenUsage();

packages/core/src/harness/token-usage.test.ts

@@ -248,4 +248,14 @@ describe('step-finish token usage extraction', () => {
       raw: { step: 2 },
     });
   });
+
+  it('defaults cache usage fields to 0 when not present in usage', async () => {
+    const usage = { inputTokens: 100, outputTokens: 50, totalTokens: 150 };
+
+    await (harness as any).processStream({ fullStream: mockStream(usage) });
+
+    const tokenUsage = harness.getTokenUsage();
+    expect(tokenUsage.cachedInputTokens).toBe(0);
+    expect(tokenUsage.cacheCreationInputTokens).toBe(0);
+  });
 });

packages/core/src/harness/types.ts

@@ -438,6 +438,17 @@ export interface TokenUsage {
   raw?: unknown;
 }
 
+/** Creates a zero-initialized TokenUsage object. */
+export function createEmptyTokenUsage(): TokenUsage {
+  return {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0,
+    cachedInputTokens: 0,
+    cacheCreationInputTokens: 0,
+  };
+}
+
 // =============================================================================
 // Observational Memory Progress
 // =============================================================================
@@ -646,7 +657,7 @@ export function defaultDisplayState(): HarnessDisplayState {
   return {
     isRunning: false,
     currentMessage: null,
-    tokenUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    tokenUsage: createEmptyTokenUsage(),
     activeTools: new Map(),
     toolInputBuffers: new Map(),
     pendingApproval: null,