Preserve Provider Response Metadata in SDK Returns

[monsieurBoutte]

Preserve Provider Response Metadata in SDK Returns

Summary

Our current workflows (for example summarization) only return the parsed object from the AI call. This strips out useful metadata from the underlying response such as finishReason and usage. We should design a return shape that preserves this information for all workflows.

Problem

• Dropping the raw response makes it harder to:
  • Inspect finishReason and other termination details.
  • Track usage for observability and billing.
  • Debug provider-specific issues.
• We also need a return shape that can work both when:
  • Calling providers via Vercel’s AI SDK, and
  • Calling Mux’s own hosted AI endpoints through the same @mux/ai SDK.

Proposed Direction

• Introduce a shared result envelope that always includes:
  • The high-level object our workflows currently return, and
  • The underlying response (or an equivalent normalized structure) that contains metadata such as finishReason and usage.
• Ensure the type can accommodate:
  • Vercel AI SDK responses, and
  • Mux-hosted API responses
    possibly via a generic or discriminated union so callers can still narrow types safely.

Tasks

• Design a common AiResult<T> (or similar) type that models object + response.
• Update existing workflow helpers to return this envelope instead of only response.object.
• Document how consumers should access metadata across both BYO-provider and Mux-hosted entry paths.