Summary

Fixes #758. Token usage was being dropped on the structured-output fallback path, so RUN_FINISHED.usage came back undefined and the engine's runOnUsage middleware hook never fired — cost-tracking and observability layers reported zero tokens.

Root cause

chat({ outputSchema, stream: true }) resolves the schema in one of two ways:

• Native — the adapter's structuredOutputStream, or the combined tools+schema path. These emit usage on their RUN_FINISHED.
• Fallback — fallbackStructuredOutputStream, used when neither is available. It wraps the non-streaming structuredOutput() and synthesizes the AG-UI lifecycle.

The fallback's structuredOutput() result does carry usage, but the synthesized RUN_FINISHED never copied it over:

let result: { data: unknown; rawText: string }   // narrowed type hid `usage`
// ...
yield { type: EventType.RUN_FINISHED, /* …no usage… */ }

This affects any provider/model that takes the fallback: Ollama, plus Anthropic and Gemini models that predate combined tools+schema support (Claude 4.5+ and Gemini 3.x use the native combined path and were unaffected).

Fix

Widen the local type to the adapter's real return type (StructuredOutputResult<unknown>, which already declares usage?) and forward it onto RUN_FINISHED with a conditional spread so adapters that don't report usage don't get a spurious usage: undefined:

let result: StructuredOutputResult<unknown>
// ...
yield {
  type: EventType.RUN_FINISHED,
  // …
  ...(result.usage ? { usage: result.usage } : {}),
}

This brings the fallback path to parity with the native streaming path (e.g. openai-base already emits usage on RUN_FINISHED the same way).

Testing

• Unit (packages/ai/tests/chat-structured-output-stream.test.ts): a regression test asserting RUN_FINISHED.usage is forwarded, and a companion test asserting the key is omitted when the adapter reports no usage.
• E2E (testing/e2e/.../anthropic-structured-usage): drives the Anthropic adapter (claude-opus-4-1, a pre-combined model, to force the fallback) through chat({ outputSchema, stream: true }) against an aimock mount whose tool-forced structured_output response carries input_tokens / output_tokens / cache_read_input_tokens, and asserts the normalized usage reaches RUN_FINISHED.usage end-to-end.
• Full @tanstack/ai unit suite (1045) and the e2e spec pass locally; types and lint are clean.

A changeset is included (@tanstack/ai patch).

Summary by CodeRabbit

• Bug Fixes
  • Fixed token usage tracking for structured output streaming with adapters that resolve schemas via non-streaming methods (e.g., Ollama, certain Anthropic/Gemini models). Token counts are now properly reported and available to observability middleware, resolving previously reported zero/undefined usage values.