Events

This page documents MobKit v0.8.34 (mirrored from v0.8.34). MobKit exposes three related event surfaces:

EventEnvelope<UnifiedEvent> merges projected Meerkat agent events with MobKit module events.
MobStructuralEventEnvelope projects structural events from the Meerkat mob-event ledger.
The WorkGraph wake stream emits bare UnifiedEvent::Module values at GET /mobkit/workgraph/facts/stream as lossy notifications.

They have different transport shapes and durability properties.

Unified event envelope

pub struct EventEnvelope<T> {
    pub event_id: String,
    pub source: String,
    pub timestamp_ms: u64,
    pub event: T,
}

#[serde(tag = "kind", rename_all = "snake_case")]
pub enum UnifiedEvent {
    Agent {
        agent_id: String,
        event_type: String,
        payload: Option<serde_json::Value>,
    },
    Module(ModuleEvent),
}

pub struct ModuleEvent {
    pub module: String,
    pub event_type: String,
    pub payload: serde_json::Value,
}

For UnifiedEvent::Agent, source must be "agent". For UnifiedEvent::Module, it must be "module". The optional agent payload is part of the wire contract and must not be dropped when matching or forwarding the event.

Agent event names

Agent event names come from Meerkat’s exhaustive event mapper. Current examples include:

Run and turn: run_started, retrying, run_completed, run_failed, turn_started, turn_completed
Model output: reasoning_delta, reasoning_complete, text_delta, text_complete
Tools: tool_call_requested, tool_result_received, tool_execution_started, tool_execution_completed, tool_execution_timed_out
Hooks: hook_started, hook_completed, hook_failed, hook_denied
Compaction: compaction_started, compaction_completed, compaction_failed
Interaction: interaction_complete, interaction_callback_pending, interaction_failed. Only the first and last are terminals; interaction_callback_pending means the interaction is paused at an external callback boundary waiting for tool results, and it resumes and closes under the same interaction_id

These strings are projections of Meerkat AgentEvent variants. MobKit does not synthesize them as module events.

Run failure payload

run_failed carries Meerkat’s typed failure fact as error_report; since Meerkat 0.7 there is no separately carried error string on the wire. MobKit’s projection (console_agent_event_payload, the single site every SSE stream, event-log row and console frame goes through) keeps the report and derives two flat keys from it, so consumers read one shape:

{
  "type": "run_failed",
  "session_id": "01a068a0-f911-7331-8187-d436145ac895",
  "error_report": {
    "class": "llm",
    "reason": { "reason_type": "llm_auth_error" },
    "message": "LLM error: authentication failed (401)"
  },
  "error": "LLM error: authentication failed (401)",
  "reason": "llm_auth_error"
}

Key	Meaning
`error_report.class`	Meerkat’s `AgentErrorClass` (`llm`, `tool`, `budget`, `auth`, `internal`, …).
`error_report.reason`	Optional typed reason. `reason_type` is the stable discriminator (`llm_auth_error`, `llm_rate_limited`, `llm_provider_error`, `llm_context_exceeded`, `hook_denied`, …); the remaining fields are variant data (`retry_after_ms`, `provider_error`, …). Absent when Meerkat attached no typed reason.
`error_report.message`	Human-readable failure text (the `Display` of the failing error).
`error`	Derived: `error_report.message`.
`reason`	Derived: `error_report.reason.reason_type`. Absent when there is no typed reason.

The console interaction_failed frame MobKit projects from run_failed carries the same payload, so frame.data.error and frame.data.reason name the failure there too. Frames MobKit mints itself (reason: "superseded_by_later_run", or error set from a delivery failure) carry only the flat keys. Meerkat’s own interaction_failed agent event carries a typed reason object (kind discriminator) whose Display is mirrored into error. The Python SDK exposes the report as RunFailed.error_report (with error_class and reason_type accessors) and derives RunFailed.error from it; the TypeScript SDK exposes RunFailedEvent.errorReport; UnifiedAgentEvent.payload carries it for query_events consumers. A retried LLM call (a 429, a network timeout) surfaces as retrying events before either terminal; a non-retryable failure (a 401 on a bad key) reaches run_failed in one round trip. The user_input frame of a console send terminates at delivered by design (the send was admitted); the turn’s outcome is the sibling interaction_complete or interaction_failed frame, not a status change on the input frame.

Merged module event names

MobKit itself generates these module event types in the merged envelope log:

`module`	`event_type`	Payload
Configured module ID	`mcp.ready`	`tools` returned by the startup probe
Configured module ID	`supervisor.warning`	Startup or runtime boundary `error`
`router`	`resolved`	Full `RoutingResolution`
`delivery`	`send`	`delivery_id`, `route_id`, `recipient`, `sink`, `status`, and `attempts`

Generic modules may supply additional event names through their own valid envelopes. Gating audit entries, memory operations, and supervisor health transitions are not currently generated as unified module events by MobKit.

WorkGraph wake events

The separate WorkGraph wake stream uses the UnifiedEvent::Module shape but serializes that value directly as SSE data. It does not wrap the value in EventEnvelope, write it to merged_events, or include it in mobkit/events/subscribe.

`module`	`event_type`	Payload
`mobkit.workgraph`	`workgraph.fact`	Lossy WorkGraph fact wake payload
`mobkit.workgraph`	`workgraph.resync_required`	Resynchronization reason and optional skipped count

Every connection begins with workgraph.resync_required and reason = "initial_sync". The stream then sends workgraph.fact wakes and can send workgraph.resync_required with reason = "lagged" after broadcast lag. It has no SSE ID, Last-Event-ID, catch-up, or replay contract. Consumers obtain authoritative graph state through the WorkGraph get, list, ready, and snapshot pull methods.

Ordering and normalization

merge_unified_events orders envelopes by:

timestamp_ms
event_id
source

There is no special agent-before-module tie rule. The module boundary accepts direct EventEnvelope<UnifiedEvent> JSON and a supported flat event form. Normalization verifies that the source agrees with the UnifiedEvent variant and rejects malformed input. It does not mint missing IDs, enforce ID uniqueness, deduplicate events, or rewrite timestamps. insert_event_sorted uses the same ordering when runtime operations add later events.

Structural mob events

The structural surface preserves a Meerkat mob-event cursor and the serialized MobEventKind payload:

pub struct MobStructuralEventEnvelope {
    pub event_id: String,
    pub cursor: u64,
    pub mob_id: String,
    pub timestamp_ms: u64,
    pub kind: String,
    pub run_id: Option<String>,
    pub step_id: Option<String>,
    pub agent_identity: Option<String>,
    pub mob_labels: BTreeMap<String, String>,
    pub run_labels: BTreeMap<String, String>,
    pub data: serde_json::Value,
}

The projection uses event_id: "mob-evt-{cursor}", preserves the upstream cursor and timestamp, maps the event kind to its snake-case name, and places the full serialized kind payload in data. Current kinds include mob_created, member_spawned, flow_started, step_dispatched, members_wired, and supervisor_escalation. The enum can grow, so clients should not depend on a fixed variant count.

Cursor persistence and replay

The structural subscriber reads from MobEventsView. With a saved cursor it uses subscribe_after(cursor); without one it starts from the latest cursor. It writes the last projected cursor to PersistentMetadataStore after projection. Cursor persistence is not event persistence:

If a persistent-state path is configured and no explicit metadata store is supplied, MobKit creates <path>/mobkit_metadata.sqlite3 for projection metadata.
That metadata stores the resume cursor, not the mob-event ledger.
.persistent_state(path) by itself keeps Mob storage in memory.
Replaying events written while MobKit was down requires an upstream Meerkat mob-event store that retained those events.

If a saved cursor is stale for the available ledger, the subscriber falls back to the latest cursor.

Access surfaces

Surface	Purpose
`mobkit/mob_events/query` JSON-RPC	Query a structural snapshot or batch
`mobkit/mob_events/subscribe` JSON-RPC	Create a subscription and receive its SSE URL
`GET /mobkit/mob_events/stream` SSE	Tail structural events with cursor and filter resume

See SSE API for stream parameters and JSON-RPC API for request and response shapes.

Lifecycle events

LifecycleStage has these exact variants:

Stage	Meaning
`MobStarted`	Runtime bootstrap began
`ModulesStarted`	All configured module startup attempts completed
`MergedStreamStarted`	The initial agent and module envelopes were merged
`ShutdownRequested`	Runtime shutdown began
`ShutdownComplete`	Runtime shutdown completed

Each LifecycleEvent contains a monotonic seq and one stage. Read the retained entries through MobkitRuntimeHandle::lifecycle_events(). ModulesStarted is not proof that every module is healthy; inspect SupervisorReport for module transitions.

Getting started

Core concepts

Guides

Unified event envelope

Agent event names

Run failure payload

Merged module event names

WorkGraph wake events

Ordering and normalization

Structural mob events

Cursor persistence and replay

Access surfaces

Lifecycle events

See also

​Unified event envelope

​Agent event names

​Run failure payload

​Merged module event names

​WorkGraph wake events

​Ordering and normalization

​Structural mob events

​Cursor persistence and replay

​Access surfaces

​Lifecycle events

​See also

Unified event envelope

Agent event names

Run failure payload

Merged module event names

WorkGraph wake events

Ordering and normalization

Structural mob events

Cursor persistence and replay

Access surfaces

Lifecycle events

See also