veryfront/run-events

Every run event surface returns rows that carry a span envelope and a payload, keyed payload and named by a catalogued type. This module owns the reader's half of that contract: the type vocabulary, display names, groups, categories and kinds, the AG-UI wire names, the envelope and row schemas, and one payload schema per type. Import it instead of writing the names or shapes out again.

The typed contract is the only one: format=typed is accepted and ignored (deprecated), and format=raw is refused, so do not send format.

RUN_EVENT_CATALOG lists each event's type, display name, reference group, filter category and semantic kind. RUN_EVENT_GROUPS, RUN_EVENT_CATEGORIES and RUN_EVENT_KINDS supply the ordered IDs and names; RUN_EVENT_CATEGORY_HEADINGS places the categories under the filter's Interactions and System headings. These are display metadata, not fields added to event payloads, and need no schema validator.

The catalog includes the legacy UNKNOWN fallback alongside current types. getRunEventCategory and getRunEventKind accept any stored type: a legacy alias resolves to its current type (RUN_EVENT_TYPE_ALIASES) and an unrecognized type falls back to system and runtime.

Every schema here is lazy and materializes through the registered SchemaValidator contract, so a consumer outside a Veryfront app must register one before the first get*Schema() call or parseTypedRunEventRow. register replaces whatever is registered, so gate it on tryResolve to leave an existing validator in place:

ts
import { register, tryResolve } from "veryfront/extensions/contracts";
import { createZodAdapter } from "@veryfront/ext-schema-zod";

if (!tryResolve("SchemaValidator")) {
  register("SchemaValidator", createZodAdapter());
}

Inside a Veryfront app, bootstrap registers the app's validator before handlers run, and the gate keeps it; never call register unconditionally there, since that would replace a lifecycle-owned validator. This module ships no fallback validator: calling a getter with nothing registered throws an error naming the contract and this registration call.

Import

ts
import {
  assertRunEventSchemaValidator,
  fromRunEventWireName,
  getRunEventCategory,
  getRunEventClass,
  getRunEventDefinition,
  getRunEventKind,
} from "veryfront/run-events";

Examples

ts
import { RUN_EVENT_CATALOG, RUN_EVENT_GROUPS } from "veryfront/run-events";

for (const group of RUN_EVENT_GROUPS) {
  const events = RUN_EVENT_CATALOG.filter((event) => event.group === group.id);
  console.log(group.name, events.map(({ type, name }) => ({ type, name })));
}
ts
import { register, tryResolve } from "veryfront/extensions/contracts";
import { createZodAdapter } from "@veryfront/ext-schema-zod";
import {
  isRunEventType,
  parseTypedRunEventRow,
  RUN_EVENT_PAYLOAD_SCHEMAS,
} from "veryfront/run-events";

// Register a validator only when nothing has: outside a Veryfront app this
// installs the Zod adapter, inside one it keeps the validator bootstrap owns.
if (!tryResolve("SchemaValidator")) {
  register("SchemaValidator", createZodAdapter());
}

const apiUrl = "https://api.veryfront.example";
const runId = "<RUN_ID>";
const token = "<TOKEN>";

const response = await fetch(`${apiUrl}/runs/${runId}/events`, {
  headers: { Authorization: `Bearer ${token}` },
});
const body = await response.json() as { data: unknown[] };

for (const raw of body.data) {
  const row = parseTypedRunEventRow(raw);
  if (!isRunEventType(row.event_type)) {
    // A type this build predates: the envelope is still valid, so keep the
    // row and render its raw payload rather than dropping it.
    console.log(row.event_type, row.span_id, row.payload);
    continue;
  }
  // Most control-plane `AGENT_RUN_*` types have no payload schema, and
  // viewer rows can be redacted: fall back to the already-validated raw
  // payload when there is no schema or the payload does not match.
  const schema = RUN_EVENT_PAYLOAD_SCHEMAS[row.event_type];
  const result = schema?.().safeParse(row.payload);
  console.log(row.event_type, row.span_id, result?.success ? result.data : row.payload);
}

Exports

Components

NameDescriptionSource
NATIVE_RUN_EVENT_TYPESThe stored types this runtime emits natively, for a consumer that needs to tell "Veryfront Code produced this" from "another producer did". Derived from NATIVE_RUN_EVENTS so the producer list stays the one declaration.source
RUN_EVENT_CATALOGRun event definitions ordered by group, then by lifecycle within each group. Includes the legacy UNKNOWN fallback; catalog membership does not imply that a type is emitted or persisted by every runtime.source
RUN_EVENT_CATEGORIESRun event filter categories in display order: which layer produced the event. ag-ui is the AG-UI core protocol, extensions is Veryfront's typed extension events, and system is the Veryfront control plane plus the legacy UNKNOWN fallback. Categories are distinct from the reference groups above.source
RUN_EVENT_CATEGORY_HEADINGSHeadings a run event filter shows its categories under, in display order.source
RUN_EVENT_CLASSESHow a reader must treat the event: a fact stands on its own, a delta only means something applied in order on top of the frames before it.source
RUN_EVENT_GROUPSRun event groups in reference and navigation order.source
RUN_EVENT_KINDSSemantic kinds in display order: what an event is about, independent of its category and group. llm is displayed as "Model".source
RUN_EVENT_PAYLOAD_SCHEMASEvery per-type payload schema, keyed by stored type, for a reader that validates a row whose type it only learns at runtime. Types without a declared payload shape (the bare control plane types) are absent, which is the signal to validate the envelope only.source
RUN_EVENT_SCHEMA_VALIDATOR_CONTRACTThe contract name every schema in this module resolves.source
RUN_EVENT_SCHEMA_VALIDATOR_PACKAGEThe package that provides it.source
RUN_EVENT_TYPE_ALIASESStored spellings the API still reads, mapped to their current type: four lowercase-dotted names and the eight pre-rename control-plane names. Rows may still carry them; new rows use the current type.source
RUN_EVENT_TYPESEvery catalogued run event type: the AG-UI core types (CUSTOM excluded, it has no typed projection), the Veryfront control plane and extension types, followed by the legacy UNKNOWN fallback.source

Functions

NameDescriptionSource
assertRunEventSchemaValidatorThrow a message a consumer can act on when no SchemaValidator is registered. Every getter in this module calls this before materializing, so the first failure explains the registration rather than surfacing the generic missing-extension throw from the contract registry.source
fromRunEventWireNameThe stored type behind an SSE frame's wire name, or null when the frame carries a name this vocabulary does not know.source
getRunEventCategoryThe filter category for a stored event_type. An unrecognized type reads as system, the catch-all, so a type newer than this build never appears as an interaction.source
getRunEventClassThe event class the API reports for a catalogued type, or null for a type this vocabulary does not know. A null is not a fact: the API's post-cutover rule leaves event_type open, so a newer API can serve a delta this build predates, and the row's event_class envelope field is the authority for it. Read that field rather than defaulting.source
getRunEventDefinitionLook up display metadata without registering a schema validator. A legacy alias resolves to its current type's definition. Returns null for an unrecognized type so callers can display its original name.source
getRunEventKindThe semantic kind for a stored event_type. An unrecognized type reads as runtime.source
isRunEventTypeReports whether a stored event_type is one this vocabulary knows.source
parseTypedRunEventRowParse one typed run event row, throwing when it does not match the contract.source
resolveRunEventTypeThe current type for a stored event_type: the type itself when catalogued, its current spelling when it is a legacy alias, or null for a type this build does not know.source
toRunEventWireNameThe wire name a catalogued type carries on an SSE frame.source

Types

NameDescriptionSource
ConversationTypedRunEventRowThe parsed conversation-scoped row: the envelope plus the row's one payload, reachable as payload and, until Phase F, as the event alias.source
ConversationTypedRunEventRowInputA conversation-scoped row as the API serves it, before getConversationTypedRunEventRowSchema collapses its two keys into one: keyed payload, or, until Phase F, by the event alias. Annotate a row you build by hand (a fixture, a stub server) with this type and parse it to get a ConversationTypedRunEventRow. A row with neither key, or an alias-only row whose alias is not a typed payload, is not assignable to it, matching what the schema rejects.source
RunEventCategoryStable identifier of a filter category.source
RunEventClassFact or delta, as the API's event_class envelope field reports it.source
RunEventDefinitionAn event type and its display metadata, separate from an emitted event payload.source
RunEventEnvelopeThe span envelope and row identity fields of a typed run event.source
RunEventGroupStable identifier of a presentation group.source
RunEventKindStable identifier of a semantic kind.source
RunEventTypeOne catalogued run event type.source
RunEventWireNameThe AG-UI wire name of a catalogued run event type.source
TypedRunEventRowA typed run event row keyed by payload.source

Constants

NameDescriptionSource
getActivityDeltaPayloadSchemaPayload carrying an activity delta. Reserved: no producer emits it yet.source
getActivitySnapshotPayloadSchemaPayload carrying an activity snapshot. Reserved: no producer emits it yet.source
getAgentRunDetachedAcceptedPayloadSchemaPayload of a detached run accepted by the runtime. Viewer events expose only the type discriminator.source
getAgentRunIntegrationConnectionRefusedPayloadSchemaPayload of a tool call refused because its integration has no usable connection. Viewers receive the same three fields.source
getChildRunStatusChangedPayloadSchemaPayload of a veryfront__invoke_agent child run's lifecycle transition.source
getConversationTypedRunEventRowSchemaThe same row as the conversation-scoped surfaces serve it: GraphQL listRunEvents, the agent platform veryfront__list_run_events tool, and GET /conversations/{conversation_id}/runs/{run_id}/events. Since the cutover every one of them keys the payload as payload, the same spelling as the run-scoped route and the SSE frames, so this schema reads payload as canonical and accepts the pre-cutover event key as a transitional alias that Phase F removes. At least one of the two must be present: a row with both parses as payload and never looks at the alias, so a stale or malformed alias beside a canonical payload does not reject the row; a row with neither is rejected with an issue naming both keys.source
getDocumentCitedPayloadSchemaPayload of a document citation attached to assistant output.source
getFileAttachedPayloadSchemaPayload of a file reference the run emitted.source
getFilesChangedPayloadSchemaPayload of a file change set a runtime proposed or applied.source
getInputRequestCreatedPayloadSchemaPayload of a form or approval input request opened for the run.source
getInputRequestUpdatedPayloadSchemaPayload of an open input request that changed.source
getMessagesSnapshotPayloadSchemaPayload carrying the authoritative message list for a stream's start.source
getModelCallCompletedPayloadSchemaModel usage recorded by the API gateway, independently of the call's outcome.source
getReasoningContentPayloadSchemaPayload carrying one reasoning content delta.source
getReasoningEndPayloadSchemaPayload that closes a reasoning block.source
getReasoningMessageContentPayloadSchemaPayload carrying one reasoning delta. contentId carries the optional segment id.source
getReasoningMessageEndPayloadSchemaPayload that closes a reasoning message. contentId carries the optional segment id.source
getReasoningMessageStartPayloadSchemaPayload that opens a reasoning message. contentId carries the optional segment id.source
getReasoningStartPayloadSchemaPayload that opens a reasoning block.source
getRunErrorPayloadSchemaPayload of a run that failed.source
getRunEventEnvelopeSchemaThe span envelope plus the row's own identity fields.source
getRunFinishedPayloadSchemaPayload of a run that finished, carrying provider and usage metadata.source
getRunLogCapturedPayloadSchemaPayload carrying captured runtime execution logs.source
getRunParkedPayloadSchemaPayload of a run parked waiting for integration authentication. Live only.source
getRunStartedPayloadSchemaPayload of a run that started.source
getRuntimeEventRecordedPayloadSchemaPayload of a runtime-native event with no AG-UI equivalent, recorded for diagnostics. value is unconstrained JSON: this is the catch-all the runtime context snapshot and the codex thread and session events use.source
getStateDeltaPayloadSchemaPayload carrying a state change. The delta stays unknown: the public profile accepts both a legacy object delta and a JSON Patch operation array.source
getStateSnapshotPayloadSchemaPayload carrying the whole client state.source
getStepFinishedPayloadSchemaPayload that closes a step, or a runtime turn when runtime is set.source
getStepStartedPayloadSchemaPayload that opens a step, or a runtime turn when runtime is set.source
getStreamHeartbeatEmittedPayloadSchemaPayload of a live stream heartbeat. Never persisted.source
getTextMessageContentPayloadSchemaPayload carrying one text delta. Apply deltas in event id order.source
getTextMessageEndPayloadSchemaPayload that closes an assistant message.source
getTextMessageStartPayloadSchemaPayload that opens an assistant message. contentId is required: the API's public normalization rejects a row without one rather than degrading it.source
getToolCallArgsPayloadSchemaPayload carrying one tool argument delta.source
getToolCallChunkPayloadSchemaPayload carrying one streamed tool chunk.source
getToolCallEndPayloadSchemaPayload that closes a tool call's argument stream.source
getToolCallResultPayloadSchemaPayload of a tool result. parentMessageId names the assistant turn, as on a tool call start. isError is null when no producer evidence exists; the API never defaults it to false.source
getToolCallStartPayloadSchemaPayload that opens a tool call. parentMessageId names the assistant turn.source
getToolCallStatusChangedPayloadSchemaPayload of a tool call status transition (pending_input, streaming_input, in_progress, completed, failed). toolCallName is null when the runtime reported a status before naming the call.source
getTypedRunEventRowSchemaA typed run event row as GET /runs/{run_id}/events and the typed SSE frames serve it.source
getUnknownRunEventPayloadSchemaPayload of a row whose stored type or CUSTOM name has no typed projection. originalType and raw carry what the row actually held.source
getUrlCitedPayloadSchemaPayload of a URL citation attached to assistant output.source