The 11 Events

One discriminated union of 11 events — every token, tool call, and result is typed.

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

1. Decode a frame

   const outcome = decodeEvent(rawFrame);

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

2. Stop at the terminal event

   import { isTerminal } from "praisonai-mobile/protocol/events";
   
   if (isTerminal(event)) return;

   After a terminal event nothing else follows.

What Happens To A Rejection

A rejection is not silent — it lands on the transcript as a dropped row.

parseFrame adds two reasons the decoder alone could not report — unparseable_json (an HTML error page or truncated body) and not_an_object (a JSON array, string, or null) — so five distinct wire failures are no longer collapsed to one missing_msg_id.

The 11 Events

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

What The Decoder Refuses

decodeEvent takes unknown, so the validation below is the wire contract — not a suggestion a buggy engine adapter can skip.

Approval choices

The decoder exports decodeApprovalChoice, and the set is exhaustive — every unknown string returns null, never a silent default.

import { decodeApprovalChoice } from "praisonai-mobile/protocol/decode";

decodeApprovalChoice("allow");   // "allow"
decodeApprovalChoice("always");  // "always"  — do NOT omit; the button is real
decodeApprovalChoice("deny");    // "deny"
decodeApprovalChoice("maybe");   // null      — never a silent default
decodeApprovalChoice("ALLOW");   // null      — case-sensitive

Event type comes from the SSE event: line, never the data payload

The event’s type is read from the SSE event: line, not from any type field inside the frame’s data object.

The engine builds the decoded event as decodeEvent({ ...parsed.value, type: frame.event }) — the event: name overwrites any type the payload carried. A delta frame whose data object happens to include type: "error" is still a delta:

// A delta frame that carries its own conflicting `type` in the payload.
// event: delta
// data: { "msg_id": "m1", "text": "kept", "type": "error" }
// -> decoded as a delta with text "kept". The `event:` line wins.

This is the shape assumption the whole 11-event contract stands on. Before #4579 the two were transposed, so a delta with type: "error" in its payload decoded as an ill-formed error, was dropped silently, and text vanished from the answer.

How A Turn Streams

Fields That Trap Readers

Error Kinds

ErrorKind selects the recovery the UI offers.

Before this, a 403 — what an engine behind a proxy or a scoped key actually returns — was classified transport, so the UI offered Retry forever instead of sending the user to credentials.

Protocol version reporting

checkProtocol in protocol/src/version.ts compares the engine’s stated version against what this client requires, and shapes a diagnostic a user can paste into a bug report. Two rules keep that diagnostic honest — they are the same absent-vs-present discipline the decoder uses for tool_result.seconds.

engine: 0 would read as “the engine answered 0” instead of “the engine did not answer”, so a version that was never stated is reported as null, not zero — a present number and an absent one are different facts. Pinned by "an engine that cannot state its version reports ABSENT, not zero".

A refusal carries one of four reasons:

The paired positive case: an engine stating exactly PROTOCOL_VERSION passes, so the check does not degenerate to “refuse everything”.

Best Practices

Related