The 11 Events

Every turn is a stream of typed events, decoded once so nothing above has to parse prose.

import { decodeEvent, isDecoded } from "praisonai-mobile/protocol/decode";

const outcome = decodeEvent(rawFrame);
if (isDecoded(outcome) && outcome.event.type === "delta") {
  render(outcome.event.text);
}

Quick Start

Decode a frame

const outcome = decodeEvent(rawFrame);

decodeEvent never throws. Every rejection is a value with a reason, so a client can count them.

Stop at the terminal event

import { isTerminal } from "praisonai-mobile/protocol/events";

if (isTerminal(event)) return;

After a terminal event nothing else follows.

Every event carries msgId. Fields listed are the ones beyond that.

Event	Purpose	Key fields	Terminal
`start`	A turn begins	`runId`	No
`delta`	Assistant text	`text` (never empty)	No
`reasoning`	Intermediate thinking	`text`	No
`tool_drafting`	A tool is being drafted (a status, not a row)	`name`	No
`tool_call`	A tool call is issued	`callId`, `name`, `args`	No
`tool_result`	A tool call returns	`callId`, `name`, `ok`, `output`, `seconds`	No
`approval_request`	The agent asks permission	`approvalId`, `callId`, `name`, `args`	No
`usage`	Cost/timing report	`chars`, `seconds`, `ttftSeconds`	No
`cancelled`	The turn was stopped	`runId`	Yes
`error`	The turn failed	`kind`, `message`	Yes
`end`	The turn completed	`userIndex`, `assistantIndex`, `versions`, `active`	Yes

How A Turn Streams

Fields That Trap Readers

callId vs approvalId are never interchangeable. callId says which row to attach the prompt to; approvalId is what gets sent back. In the two-approval case the prompts arrive in the opposite order to their tool rows, so zipping by index crosses rm with curl.

end.userIndex === null means “not on disk”. The write failed, so Fork and Delete must be withheld. Index 0 is a valid, persisted message — a falsy check (if (!userIndex)) is a trap.

Terminal events are mutually exclusive and final. After end, cancelled, or error, nothing else may follow. A cancelled turn is never persisted, so no end and no usage follow it.

Unknown ErrorKind degrades to "internal". decode.ts maps any kind it does not recognise to "internal" rather than dropping the event, so a newer engine’s category still reaches the user.

Error Kinds

ErrorKind selects the recovery the UI offers.

Kind	Meaning
`auth`	The provider rejected the credential — send the user to settings.
`rate_limit`	Retrying is meaningful.
`empty`	The engine produced no output at all.
`transport`	The stream broke; the engine may be fine.
`protocol`	Client and engine disagree about the contract.
`internal`	Anything else, including unrecognised kinds.

Best Practices

Trust tool_result.ok, never the output

ok is the only signal of tool success. Inferring success from a non-empty output is the exact defect the field prevents.

Route approvals by approvalId

Bind a decision to a row by approvalId, not by position — position holds only while exactly one approval is outstanding.

Treat null as a real value

For end.userIndex and tool_result.seconds, null means “unknown / not persisted”, which is different from 0 and from absent.

Approvals & Cancellation

The human-in-the-loop flow on mobile.

Capabilities & Gaps

Which events each engine emits today.

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

The 11 Events

Quick Start

The 11 Events

How A Turn Streams

Fields That Trap Readers

Error Kinds

Best Practices

Approvals & Cancellation

Capabilities & Gaps

​Quick Start

​The 11 Events

​How A Turn Streams

​Fields That Trap Readers

​Error Kinds

​Best Practices

​Related

Approvals & Cancellation

Capabilities & Gaps

Quick Start

The 11 Events

How A Turn Streams

Fields That Trap Readers

Error Kinds

Best Practices

Related