marker
Agent-prose embed marker grammar.
The Mastra agent is instructed to defer visualizations to the host
UI by embedding markers in its markdown reply; the UI parses them
out and swaps in the matching slot. This module is the single
source of truth for that grammar so every consumer parses markers
the same way and can’t drift from the shapes documented on
ChartSchema / StatementDataSchema in protocol.ts
and the instructions the server hands the model.
One grammar, open-ended type. A marker is [<type>:<id>]. The
<type> is an opaque token that names the embed kind; the host
resolves it against the generic /embed/<type>/<id> route, which
404s any type the server doesn’t register. The grammar does NOT
hard-code the known types - new embed kinds work end to end
without touching this regex. Today the server registers:
[chart:<chartId>]- the<chartId>is a v4 UUID minted by the chart subsystem (prepare_chart/render_data) and resolves to a cached Echarts spec.[data:<statementId>]- the<statementId>is a Databricks statement id (a time-ordered UUID) and resolves to the statement’s rows.
The <id> of a real embed is UUID-shaped (8-4-4-4-12 hex): both
id kinds above are UUIDs, just different versions (chart = v4,
statement = v7-style). The grammar deliberately captures ANY
non-bracket id token, not just UUID-shaped ones, so a fabricated
marker the model glued together from a label
(e.g. [chart:placeholder] or
[chart:01f163b6-1eac-region-fill-oos]) still parses as a marker.
Matching it - rather than letting the broad regex miss it - is what
lets the host UI consume and obscure the bogus marker instead of
leaking the literal [chart:...] text into the rendered prose.
Whether an id is a genuine embed is a separate isUuid
check the caller runs on ParsedMarker.id.
Parse everything through parseMarkers, validate the id with isUuid, and branch on the returned ParsedMarker.type.