Class: UiMapper

Defined in: entries/vercel-ui/UiMapper.ts:57

UiMapper -- the gateway's shapes as the Vercel chat client's shapes, and back

About

Turns become messages, events become chunks, the client's approvals become decisions.

The pure translation between what the gateway stores and streams (turns, events, pause envelopes) and what useChat draws and consumes (UIMessage, UIMessageChunk). No gateway, no config, no I/O: every method takes data and returns data.

• One answer is one assistant message (D34): the assistant and tool turns up to the next user turn fold into it, a step-start part before each model step.
• Tools are dynamic-tool parts: the gateway's tools are registered at runtime, the client renders them by toolName.
• The SDK's approval card speaks for a TOOL_APPROVAL pause (D35); the approval id is the pauseId (D110).

AIGatewayVercelUi drives it for the HTTP case; an application on another transport (a WebSocket, a resumable stream) composes it with the gateway's events itself.

Who needs it

AIGatewayVercelUi.chat, history and resume; an application that streams on its own transport.

Pitfalls

The id of a streamed answer (createChunkWriter) and the id of the same answer in the history (its first turn's id) differ: the client replaces its messages with history when it reopens the thread, it never merges the two.

Constructors

Constructor

new UiMapper(): UiMapper

Returns

UiMapper

Methods

createChunkWriter()

createChunkWriter(__namedParameters): IUiChunkWriter

Defined in: entries/vercel-ui/UiMapper.ts:230

createChunkWriter -- a writer for the chunks of one streamed answer

About

One writer per call; feed it the call's events, then its response.

threadId when the thread exists already; a new thread's id reaches the client with the response's metadata.

Parameters

__namedParameters

messageId

string

threadId?

string

Returns

IUiChunkWriter

---

toApprovalResponses()

toApprovalResponses(__namedParameters): IUiApprovalResponses | undefined

Defined in: entries/vercel-ui/UiMapper.ts:186

toApprovalResponses -- the SDK's Approve / Reject as the client sent it back (D35)

About

One decision per approval-responded tool part of the last assistant message.

Undefined when the last message is not an assistant message with approval responses: the request is then a new prompt. Approve is APPROVE; Reject is REJECT with the card's reason as the text the model reads. Every response names the same pause (its approval.id); two pauses in one message is a 400.

Parameters

__namedParameters

messages

TGatewayUiMessage[]

Returns

IUiApprovalResponses | undefined

---

toPrompt()

toPrompt(__namedParameters): object

Defined in: entries/vercel-ui/UiMapper.ts:160

toPrompt -- the last user message of a chat request as the gateway's prompt and files

About

Only the last message counts: the gateway holds the history, the client's copy is never the truth.

The text parts joined, the file parts as sent (the config's files.fromUi resolves them). A last message that is not the user's is a 400.

Parameters

__namedParameters

messages

TGatewayUiMessage[]

Returns

object

files

files: FileUIPart[]

text

text: string

---

toUiMessages()

toUiMessages(__namedParameters): Promise<TGatewayUiMessage[]>

Defined in: entries/vercel-ui/UiMapper.ts:70

toUiMessages -- the turns of a thread, and its pause, as the messages a chat UI draws

About

The whole thread, oldest first, one message per user turn and one per answer.

A tool call of the pause is drawn as the SDK's approval request (TOOL_APPROVAL) or as a call without output (USER_QUESTION: the application renders the form from the call's input). A RESULT_REVIEW pause lands as pause in the metadata of the last assistant message, or of an empty one when the draft has no turns (the asker never sees the draft, D111). Without resolveFileUrl the file parts are left out: a file part needs a url.

Parameters

__namedParameters

pause?

IUiPause

resolveFileUrl?

(args) => Promise<string>

turns

ITurn[]

Returns

Promise<TGatewayUiMessage[]>