appendUserMessage
Appends a message the client composed itself, and returns the transcript it produced.
The one thing an event stream cannot tell a client: what its own user just said. The protocol carries a user message only inside MESSAGES_SNAPSHOT, which replaces the transcript -- and replaces it with a lossy rebuild, in which the order of a sentence and the tool call that followed it is gone (see replaceMessages). Synthesising a snapshot to show the sender their own line would therefore degrade every turn already on screen, every time they sent one. So the local turn is appended rather than folded, and this is the only entry point that is not an event.
Appending does not finish the assistant turn, it detaches it: a message sent while the agent is still talking means the next assistant part belongs in a new bubble, not that the words arriving now stop arriving. What was streaming keeps streaming, and is settled when the run ends, exactly as an ACTIVITY_SNAPSHOT mid-stream is.
This is bookkeeping for the screen, not for the wire. Sending the message is the caller's -- agui-agent's AgentSession.send appends here and puts the same message in the run input, and a run whose server answers with a MESSAGES_SNAPSHOT replaces what was appended with the server's own copy of it.
Parameters
the local turn. Its id is subject to the same de-duplication as an id off the wire, so a caller that reuses one gets a second message rather than a corrupted first. It is not an id a later snapshot reconciles against: replaceMessages rebuilds the whole transcript from the snapshot, so what replaces this message is the list, not a match.