Event schema

16 event types

One envelope, typed payloads

The Python TypedDict schema is the source of truth and the console mirrors it in zod. Unknown envelope fields pass through, but ordering and idempotency are enforced.

Event envelope

packages/promptetheus/promptetheus/schema.py mirrors into apps/console/src/lib/schema.ts. Order by (session_id, seq), never by timestamp.

Field	Type	Required	Notes
type	EventType	required	One of the event types exported by schema.py and mirrored in the console schema.
session_id	string	required	Trace session id. The SDK generates one when callers do not provide one.
timestamp	ISO 8601 string	required	Client clock timestamp. Informational only; ordering uses seq.
seq	integer >= 0	required	Monotonic per-session sequence number assigned before enqueue.
idempotency_key	string	required	Stable retry key, normally <session_id>:<instance_nonce>:<seq>.
payload	object	required	Event-specific payload object.
metadata	object	optional	Optional metadata object. SDK helpers take metadata explicitly, not open kwargs.
span_id	string	optional	Optional run-tree span id for events emitted inside a Session.span block.
parent_id	string \| null	optional	Optional enclosing span id. Timeline order still uses seq.

user_message

User input or instruction captured in the trace.

content: string
metadata: #/definitions/voice_message_metadata

2 payload fields

agent_message

Agent response or claim, including terminal success claims.

content: string
metadata: #/definitions/voice_message_metadata

2 payload fields

tool_call

Tool invocation with tool_name, arguments, and optional call_id.

tool_name: string
arguments: object
call_id: string
metadata: object

4 payload fields

tool_result

Tool result or tool error associated with a call_id.

call_id: string
result: any
error: string
metadata: object

4 payload fields

retrieval

Retrieval query plus returned document metadata.

query: string
documents: array
metadata: object

3 payload fields

browser_action

Browser click, fill, navigation, submit, or related UI action.

action: string
target: string
url: string
metadata: object

4 payload fields

dom_snapshot

Observed browser state, visible text, selected values, and warnings.

url: string
visible_text: string
selected_values: object
warnings: string[]
metadata: object

5 payload fields

screenshot

Screenshot artifact reference or staged screenshot source.

artifact_id: string
storage_path: string
size_bytes: integer
source_type: "bytes" | "path"
metadata: object

5 payload fields

replay_artifact

Replay artifact identity and event time map for private storage.

artifact_id: string
artifact_type: "screen_recording" | "audio_recording"
storage_path: string
started_at: string
ended_at: string

8 payload fields+3 more

goal_check

Explicit user-goal verdict emitted by the agent or test harness.

passed: boolean
mismatches: string[]
metadata: object

3 payload fields

state_change

Named state transition, including span_start and span_end markers.

name: string
before: any
after: any
span_name: string
duration_ms: integer

6 payload fields+1 more

session_end

Terminal session status event used as the canonical status transition.

status: string
error: string
metadata: object

3 payload fields

llm_call

reserved

Reserved event type for future LLM framework adapters.

model: string
prompt_ref: string
messages_ref: string
input_tokens: integer
output_tokens: integer

7 payload fields+2 more

score

Human or automated score attached to the session.

name: string
value: number | boolean
comment: string
source: string
metadata: object

5 payload fields

error

Captured exception or handled error richer than a tool_result error string.

message: string
error_type: string
traceback: string
handled: boolean
metadata: object

5 payload fields

metric

Numeric metric emitted during the run.

name: string
value: number
unit: string
metadata: object

4 payload fields