Skip to main content
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.
The event’s own 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, with turn.update marking pauses in between.
Emit 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

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.
Deltas accumulate against the 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.
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:
Every field except 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 the id 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 a threadId, 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:
Note the asymmetry between the two envelopes: createTurn yields { event }, while listEvents returns { turnId, event }. Streaming is scoped to one turn; history spans many, so it labels each event with its turn.