Token usage and cost accounting: messageMetadata, cumulative usage, and per-feature attribution

You cannot manage what you do not measure. AI SDK 7 gives you usage at three levels; wire all three before the bill surprises you.

Level 1: per-call usage. generateText/streamText results expose usage. In v7 the shape changed:
- usage.inputTokenDetails.cacheReadTokens (was usage.cachedInputTokens)
- usage.outputTokenDetails.reasoningTokens (was usage.reasoningTokens)
- result.usage accumulates across steps (was result.totalUsage)

Level 2: per-message metadata. Use the messageMetadata callback in toUIMessageStream to attach token counts and model id to each message:

toUIMessageStream({
  stream: result.stream,
  messageMetadata: ({ part }) => {
    if (part.type === 'start') return { createdAt: Date.now(), model: 'your-model-id' };
    if (part.type === 'finish') return { totalTokens: part.totalUsage?.totalTokens };
  },
});

Type the message as UIMessage[YourMetadata] with a zod schema for safety.

Level 3: per-feature attribution. Pass telemetry: { functionId: 'support-draft' } on every call so traces and cost dashboards group by feature.

Rules:
1. Migrate any code reading usage.cachedInputTokens or result.totalUsage. Those paths are gone in v7 and read as undefined, which silently zeroes your accounting.
2. Accumulate usage across steps for agentic calls; single-step usage understates tool-heavy turns badly.
3. Store per-message token counts in your chat store alongside the messages. Reconstructing cost from logs later is painful.
4. Alert on anomalies: a sudden 10x in input tokens usually means a context bug (whole history re-sent, or a runaway tool loop), not heavier usage.
5. Keep usage out of the client-visible payload unless the UI needs it. Token counts are operational data; expose only what the UI renders.