TrueForge 0.185.0+ introduces breaking changes to turn lifecycle - turns now pause when waiting for user input.
Click here to view the documentation for older versions.
createTurn and subscribeToTurn are async generators. Each value they yield is an envelope, not a bare event:
TurnStreamingEvent is a discriminated union of the concrete event shapes below.
Import it and TurnStreamData from @truefoundry/trueforge-ui to type a custom
server’s output. TypeScript checks the fields of typed events; JSON received over
the network still needs validation before it is used as an event.Individual event interfaces are defined in
@truefoundry/trueforge-assistant-ui-runtime/server; the UI package re-exports the
streaming union, so most hosts do not need a direct runtime import.id is the resume cursor. A reconnecting client calls
subscribeToTurn with the id of the
last event it applied, as afterEventId (replay what follows) or fromEventId (replay from that
event, used to rebuild a message that was still streaming). Event ids must therefore be unique within
the turn and sort in the order you emit them.
Turn lifecycle
Every turn is bracketed by two lifecycle events, withturn.update marking pauses in between.
turn.created first, then content events, then exactly one turn.done. turn.done
carries a terminal state — done, cancelled, or error — each with a completedAt. A stream
that ends without turn.done leaves the UI believing the turn is still running, unless the last
turn.update paused it.
turn.update is the authoritative signal that the turn is waiting or working again. Emit
{ status: "paused" } after the requests that need the user (see Pausing for the user),
and { status: "running" } once every request is answered and the turn continues. The UI treats
a paused turn as working again only after that running update, not when new content arrives.
Content events
model.message — a complete assistant message
model.message — a complete assistant message
content is either a plain string or an array of parts when the message mixes text with
images or a refusal. reasoningContent populates the reasoning card. toolCalls carries
fully-formed calls — see the tool calls section below.model.message.delta — incremental text
model.message.delta — incremental text
id of the message they belong to, so reuse one id across
every delta for a given message. content on a delta is the increment, not the running
total.contentBlocks carries block-level deltas, used for streaming images alongside text, keyed
by index. Both the camelCase and snake_case spellings are accepted; emit
contentBlocks in new code.tool.response — the result of a tool call
tool.response — the result of a tool call
toolCallId must match the id of the ToolCall this responds to. content is a string —
serialize structured results yourself.Tool calls
function.arguments is a JSON string, not an object. toolInfo drives presentation: the
mcp variant is what lets the UI label a call with the server it came from, and the open third
variant lets you introduce your own tool categories.
Streaming a call in pieces uses a delta shape keyed by position:
index is optional, because a call is assembled across several deltas —
typically id and function.name first, then function.arguments in fragments. Accumulate by
index within the message.
Pausing for the user
Three events tell the UI a turn cannot proceed unattended:tool.response_required has the identical shape and asks the user to supply a result rather
than approve one. A ToolCallRef needs both the tool call’s id and sourceEventId — the id
of the event that emitted the call — so the UI can attach the prompt to the right card.
authUrl is the URL the popup opens. See MCP OAuth.
After emitting one or more of these, emit turn.update with { status: "paused" }. The turn
stays open: the UI answers through
sendTurnEvents on the same
turn, and you continue it with turn.update { status: "running" } once nothing is left open.
User events
Every answer the UI sends is stored as an event on the turn, with theid and createdAt your
server assigned. Return them from sendTurnEvents, and include them when you replay the turn
through subscribeToTurn, listTurnEvents, or listEvents.
toolCallId matches the call the request named. A policy has no toolCallId: it settles every
pending approval for the same serverName + name. A user.mcp_auth_continue closes the
mcp.auth_required prompt; if sign-in is still missing, emit a new mcp.auth_required.
Sub-agents
Sub-agents are modelled as separate threads. Nearly every event carries athreadId, and the
UI groups events by it.
parent is what nests a sub-agent under the tool call that spawned it: the parent thread’s
threadId plus the toolCallId. agentInfo populates the sub-agent card — name, the input
it was given, and optionally the model it runs.
Sandboxes and MCP setup
sandboxId is what you pass to
downloadSandboxFile to retrieve artifacts the
agent produced.
mcp.initialize ({ type, id, createdAt, threadId }, plus any additional fields you attach)
reports MCP server startup.
The unions
The distinction is that
PersistedTurnEvent holds the settled record of a turn, while
TurnStreamingEvent adds the transient deltas that only matter live. This is why listing a
turn’s history yields no deltas — the assembled model.message is stored instead.
listEvents returns a session-level wrapper that identifies the turn rather than a position: