StreamProcessor doesn't accumulate AG-UI event metadata onto UIMessage - is per-message metadata merging planned?

[DoronYitz]

Question

The AG-UI spec defines metadata merging into messages: every message-building
event carries an optional metadata, and the consumer folds each event's
metadata into the message it builds — last-write-wins, key by key
(AG-UI › Concepts › Metadata › "Merging into messages").
The spec names the TypeScript client as the reference consumer.

Does @tanstack/ai intend to implement this? Today it doesn't appear to, and
UIMessage has no metadata field to receive it. I'd like per-message metadata
to be preserved onto the resulting UIMessage - including on user messages,
where the metadata arrives inside a MESSAGES_SNAPSHOT rather than through streamed
TEXT_MESSAGE_* events (those are always role: "assistant" per the spec).

Versions

• @tanstack/ai: 0.43.0
• @tanstack/ai-client: 0.23.0

Current behavior

• UIMessage has no metadata field:

  interface UIMessage<TData = unknown> {
  	id: string;
  	role: 'system' | 'user' | 'assistant';
  	parts: Array<MessagePart<TData>>;
  	createdAt?: Date;
  	// no `metadata`
  }

• In StreamProcessor, event metadata is read only for tool calls
  (TOOL_CALL_START folds chunk.metadata onto the ToolCallPart) and
  interrupt descriptors.

• The TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END handlers
  read only messageId / role / delta / content. Event metadata is never
  read, so it never reaches the message.

• The text-part updater builds { type: 'text', content } only — no metadata slot
  is populated.

• MESSAGES_SNAPSHOT normalization rebuilds user messages as
  { id, role, parts }, dropping any per-message metadata.

Result: tool-call metadata survives, but message-level metadata is silently
discarded.

Reproduction

User message (via MESSAGES_SNAPSHOT)

A user message carries its own metadata inside the snapshot:

{
  "type": "MESSAGES_SNAPSHOT",
  "messages": [
    {
      "id": "u1",
      "role": "user",
      "content": "Show me failed logins",
      "metadata": {"author": {"id": "user-42", "name": "Dana"}}
    }
  ]
}

Expected (per spec — the message keeps its own metadata):

{
  "id": "u1",
  "role": "user",
  "parts": [{"type": "text", "content": "Show me failed logins"}],
  "metadata": {"author": {"id": "user-42", "name": "Dana"}}
}

Actual: snapshot normalization rebuilds the user message as { id, role, parts },
so metadata is dropped.

Assistant message (via streamed TEXT_MESSAGE_*)

For completeness, the same loss happens on the streaming path (metadata on the
terminal event, as the spec recommends for end-of-message values):

{"type":"TEXT_MESSAGE_START","messageId":"m1","role":"assistant","metadata":{"source":"openai","stage":"start"}}
{"type":"TEXT_MESSAGE_CONTENT","messageId":"m1","delta":"Hello","metadata":{"stage":"content"}}
{"type":"TEXT_MESSAGE_END","messageId":"m1","metadata":{"stage":"end","usage":{"output":340},"traceId":"abc-123"}}

Expected (per spec):

{
	"id": "m1",
	"role": "assistant",
	"metadata": {
		"source": "openai",
		"stage": "end",
		"usage": {"output": 340},
		"traceId": "abc-123"
	}
}

Actual: the assembled UIMessage has no metadata; all metadata is lost.

Use case (why this matters)

A common need is attaching declared, typed per-message information that is only
known as the message completes — token usage per message, finish reason, trace id,
and message attribution/author in multi-user conversations. The AG-UI metadata
channel is the sanctioned home for this, but because it isn't accumulated onto
UIMessage, there's no supported per-message home for that data.

Proposed behavior

1. Add metadata?: Record<string, any> to UIMessage.
2. In StreamProcessor, merge each message-building event's metadata into the
   target message (keyed by messageId), last-write-wins, key by key —
   mirroring the existing tool-call metadata handling.
   • TEXT_MESSAGE_START / _CONTENT / _END → merge into the message.
   • TOOL_CALL_RESULT → merge into the tool message it creates.
   • MESSAGES_SNAPSHOT → preserve each message's own metadata (event-level
     metadata not merged).
3. Replace values whole (no deep merge), per spec.
4. Respect the reserved ag-ui key.
5. Ensure outbound serialization round-trips UIMessage.metadata.

[AlemTuzlak]

I work in CopilotKit (the owner of the AG-UI protocol) and I helped refine the metadata spec and it released either yesterday or today. We plan to support it but we just didn't have time to implement it yet

[DoronYitz]

Thanks for the quick response!

A related follow-up: when using TanStack's Chat sendMessage, will there be a way to attach metadata to the optimistic user UIMessage it creates?

Currently, sendMessage only accepts a string or MultimodalContent (neither of which has a metadata slot). While append takes a full UIMessage, UIMessage also lacks a metadata field, leaving no way to set per-message metadata on the user turn. Is this expected to change with the UIMessage.metadata support discussed above?