> ## Documentation Index > Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # veryfront/run-events > The typed run event contract the Veryfront API publishes. A run event surface read with `format=typed` returns rows that carry a span envelope and a payload named by a catalogued type. This module owns the reader's half of that contract: the type vocabulary, 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. 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 theme={null} import { assertRunEventSchemaValidator, fromRunEventWireName, getRunEventClass, isRunEventType, parseTypedRunEventRow, toRunEventWireName, } from "veryfront/run-events"; ``` ## Examples ```ts theme={null} 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 = ""; const token = ""; const response = await fetch(`${apiUrl}/runs/${runId}/events?format=typed`, { 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; } // The sixteen control-plane `AGENT_RUN_*` types have no payload schema: // the API owns their shape and sanitizes it before a reader ever sees // it, so fall back to the already-validated raw payload for those. 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 | Name | Description | Source | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `NATIVE_RUN_EVENT_TYPES` | The 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `RUN_EVENT_CLASSES` | How 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `RUN_EVENT_PAYLOAD_SCHEMAS` | Every 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 sixteen control plane types) are absent, which is the signal to validate the envelope only. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `RUN_EVENT_SCHEMA_VALIDATOR_CONTRACT` | The contract name every schema in this module resolves. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/schema-validator.ts) | | `RUN_EVENT_SCHEMA_VALIDATOR_PACKAGE` | The package that provides it. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/schema-validator.ts) | | `RUN_EVENT_TYPES` | Every catalogued run event type, in the API's declaration order: the AG-UI core types (`CUSTOM` excluded, it has no typed projection), the Veryfront control plane types, and the twelve extension types that replaced the registered `CUSTOM` names, followed by `UNKNOWN`. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | ### Functions | Name | Description | Source | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `assertRunEventSchemaValidator` | Throw 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/schema-validator.ts) | | `fromRunEventWireName` | The stored type behind an SSE frame's wire name, or null when the frame carries a name this vocabulary does not know. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `getRunEventClass` | The 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `isRunEventType` | Reports whether a stored `event_type` is one this vocabulary knows. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `parseTypedRunEventRow` | Parse one typed run event row, throwing when it does not match the contract. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `toRunEventWireName` | The wire name a catalogued type carries on an SSE frame. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | ### Types | Name | Description | Source | | ------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | `ConversationTypedRunEventRow` | A typed run event row keyed by `event`, as the conversation surfaces serve it. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `RunEventClass` | Fact or delta, as the API's `event_class` envelope field reports it. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `RunEventEnvelope` | The span envelope and row identity fields of a typed run event. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `RunEventType` | One catalogued run event type. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `RunEventWireName` | The AG-UI wire name of a catalogued run event type. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/vocabulary.ts) | | `TypedRunEventRow` | A typed run event row keyed by `payload`. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | ### Constants | Name | Description | Source | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `getActivityDeltaPayloadSchema` | Payload carrying an activity delta. Reserved: no producer emits it yet. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getActivitySnapshotPayloadSchema` | Payload carrying an activity snapshot. Reserved: no producer emits it yet. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getChildRunStatusChangedPayloadSchema` | Payload of an `invoke_agent` child run's lifecycle transition. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getConversationTypedRunEventRowSchema` | The same row as the conversation-scoped surfaces serve it, where the payload key is `event` rather than `payload`. GraphQL `agentRunEvents`, the MCP `get_agent_run_events` tool, and `GET /conversations/{conversation_id}/runs/{run_id}/events` all use this spelling; the run-scoped route and the SSE frames use `payload`. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `getDocumentCitedPayloadSchema` | Payload of a document citation attached to assistant output. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getFileAttachedPayloadSchema` | Payload of a file reference the run emitted. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getFilesChangedPayloadSchema` | Payload of a file change set a runtime proposed or applied. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getInputRequestCreatedPayloadSchema` | Payload of a form or approval input request opened for the run. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getInputRequestUpdatedPayloadSchema` | Payload of an open input request that changed. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getMessagesSnapshotPayloadSchema` | Payload carrying the authoritative message list for a stream's start. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningContentPayloadSchema` | Payload carrying one reasoning content delta. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningEndPayloadSchema` | Payload that closes a reasoning block. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningMessageContentPayloadSchema` | Payload carrying one reasoning delta. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningMessageEndPayloadSchema` | Payload that closes a reasoning message. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningMessageStartPayloadSchema` | Payload that opens a reasoning message. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getReasoningStartPayloadSchema` | Payload that opens a reasoning block. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRunErrorPayloadSchema` | Payload of a run that failed. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRunEventEnvelopeSchema` | The span envelope plus the row's own identity fields. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `getRunFinishedPayloadSchema` | Payload of a run that finished, carrying provider and usage metadata. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRunLogCapturedPayloadSchema` | Payload carrying captured runtime execution logs. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRunParkedPayloadSchema` | Payload of a run parked waiting for integration authentication. Live only. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRunStartedPayloadSchema` | Payload of a run that started. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getRuntimeEventRecordedPayloadSchema` | Payload 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getStateDeltaPayloadSchema` | Payload carrying a state change. The delta stays `unknown`: the public profile accepts both a legacy object delta and a JSON Patch operation array. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getStateSnapshotPayloadSchema` | Payload carrying the whole client state. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getStepFinishedPayloadSchema` | Payload that closes a step, or a runtime turn when `runtime` is set. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getStepStartedPayloadSchema` | Payload that opens a step, or a runtime turn when `runtime` is set. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getStreamHeartbeatEmittedPayloadSchema` | Payload of a live stream heartbeat. Never persisted. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getTextMessageContentPayloadSchema` | Payload carrying one text delta. Apply deltas in event id order. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getTextMessageEndPayloadSchema` | Payload that closes an assistant message. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getTextMessageStartPayloadSchema` | Payload that opens an assistant message. `contentId` is required: the API's public normalization rejects a row without one rather than degrading it. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallArgsPayloadSchema` | Payload carrying one tool argument delta. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallChunkPayloadSchema` | Payload carrying one streamed tool chunk. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallEndPayloadSchema` | Payload that closes a tool call's argument stream. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallResultPayloadSchema` | Payload of a tool result. `isError` is `null` when no producer evidence exists; the API never defaults it to false. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallStartPayloadSchema` | Payload that opens a tool call. `parentMessageId` names the assistant turn. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getToolCallStatusChangedPayloadSchema` | Payload 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](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getTypedRunEventRowSchema` | A typed run event row as `GET /runs/{run_id}/events?format=typed` and the typed SSE frames serve it. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/envelope.ts) | | `getUnknownRunEventPayloadSchema` | Payload of a row whose stored type or CUSTOM name has no typed projection. `originalType` and `raw` carry what the row actually held. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) | | `getUrlCitedPayloadSchema` | Payload of a URL citation attached to assistant output. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/run-events/payload.ts) |