Two-phase message parse: tries the strict schema first, then falls back to
the envelope to distinguish unknown-but-valid types (safe to ignore during
rolling upgrades) from genuinely malformed messages.
Return value when ok: false:
malformed: true — message doesn't have a { type: string } shape (likely
corrupt data), OR its type is one of knownTypes but it still failed
strict validation (e.g. a tool_result missing toolCallId); both should
warn
malformed: false — has a valid type field whose value is unrecognised;
safe to ignore (e.g. new message type from a newer server version)
Passing knownTypes is what separates "unknown newer-version type" from
"known type that failed validation" — without it, an invalid known message
is silently swallowed as if it were a forward-compat unknown type. When
parsing client→server messages, pass CLIENT_MESSAGE_TYPES as
knownTypes.
Two-phase message parse: tries the strict schema first, then falls back to the envelope to distinguish unknown-but-valid types (safe to ignore during rolling upgrades) from genuinely malformed messages.
Return value when
ok: false:malformed: true— message doesn't have a{ type: string }shape (likely corrupt data), OR itstypeis one ofknownTypesbut it still failed strict validation (e.g. atool_resultmissingtoolCallId); both should warnmalformed: false— has a validtypefield whose value is unrecognised; safe to ignore (e.g. new message type from a newer server version)Passing
knownTypesis what separates "unknown newer-version type" from "known type that failed validation" — without it, an invalid known message is silently swallowed as if it were a forward-compat unknown type. When parsing client→server messages, pass CLIENT_MESSAGE_TYPES asknownTypes.