Telemetry and Events

Liminal emits structured runtime events through the harness emitter. These power UI rendering, eval traces, and observability.

Core Event Categories

• conversation: text, error, turn_end
• idle personality pulse (optional, AGENT_HEARTBEAT=1): heartbeat_scheduled, heartbeat_started, heartbeat_completed, heartbeat_skipped
• tool lifecycle: tool_start, tool_delta, tool_approval, tool_result, tool_timing
• orchestration: subtask_spawned, subtask_output, subtask_complete
• context/runtime: context_compressed, persona_changed

Long-Horizon Runtime Events

• execution_state
• contract_transition
• contract_violation
• recovery_action
• drift_detected
• runtime_heartbeat
• vault_activity
• runtime_pref_detected
• runtime_pref_changed
• runtime_pref_persisted
• runtime_pref_rejected

These events make long-run behavior inspectable and testable.

Turn-End Metrics

turn_end includes harnessMetrics, commonly containing:

• tools invoked this send
• spawn call count
• parallel batch size
• working-state preview
• epistemic state snapshot
• execution state snapshot
• vault metrics

Event Semantics Guidance

• heartbeat: per-round health signal, not success indicator
• drift_detected: policy-level drift observation; may or may not trigger replan
• contract_violation: pre-dispatch policy block
• vault_activity: advisory and write/read/search telemetry, includes skips/reasons
• runtime_pref_detected: internal LLM identified a user preference mutation intent
• runtime_pref_changed: in-session preference patch applied
• runtime_pref_persisted: preference file write succeeded
• runtime_pref_rejected: risky change rejected or persistence failed

Consumers

• TUI reducer
• Web SSE reducer
• Eval trace capture
• external logs (if session/eval sinks are enabled)

Operational Practice

• treat event ordering as part of UI correctness
• preserve backwards compatibility for event payload fields where possible
• add new events with matching eval assertions to avoid silent regressions