pub trait ThreadObserver {
type SubscribeRequest: Send + 'static;
// Required method
fn on_event(&self, thread_id: &ThreadId<str>, event: &AgentEvent);
// Provided method
fn on_subscribe(
&self,
_thread_id: &ThreadId<str>,
_request: Self::SubscribeRequest,
_snapshot: ReplaySnapshot,
) { ... }
}Expand description
Observes a thread’s execution and commits any platform state derived from it.
The step pipeline calls these methods at exact points in its execution — there is no intermediate channel or forwarding task — which gives two guarantees:
- Ordering:
on_eventis invoked synchronously at the moment the event is emitted, in the same executor poll that produced it. An embedding that broadcasts events to subscribers and answers attach requests fromon_subscribetherefore gets exactly-once delivery for free: an event is either already reflected in theReplaySnapshota new subscriber receives, or it is broadcast to that subscriber afterwards — never both, never neither. - Durability: stateful events are emitted after the runtime has awaited
their corresponding
StateStoretransition.
Implementations that need mutable state should use interior mutability
(RefCell); the methods take &self so the runtime can hold shared
references across a step.
Required Associated Types§
Sourcetype SubscribeRequest: Send + 'static
type SubscribeRequest: Send + 'static
The attach-request type routed to running threads (see
RunningSystem::subscribe).
Embeddings that do not use the local driver can use ().
Required Methods§
Sourcefn on_event(&self, thread_id: &ThreadId<str>, event: &AgentEvent)
fn on_event(&self, thread_id: &ThreadId<str>, event: &AgentEvent)
A display event was emitted. Called synchronously at the emission point; keep this fast (fan-out, buffering).
Provided Methods§
Sourcefn on_subscribe(
&self,
_thread_id: &ThreadId<str>,
_request: Self::SubscribeRequest,
_snapshot: ReplaySnapshot,
)
fn on_subscribe( &self, _thread_id: &ThreadId<str>, _request: Self::SubscribeRequest, _snapshot: ReplaySnapshot, )
A subscriber attached to a running thread (local driver mode only; step-mode embeddings never receive this call).
This is the live-attach hook: when a client attaches to a thread
that is already running (via
RunningSystem::subscribe), the
driver produces a ReplaySnapshot — including in-memory state that
exists nowhere else, like the partially streamed turn and in-progress
reasoning — and hands it to the observer together with the
embedding-specific request. The implementation should render the
snapshot into its client-facing catch-up message and then register the
subscriber in the same list its on_event fan-out
broadcasts to.
The registration lives on the observer (rather than on
RunningSystem) for two reasons: only the
embedding knows its client message type and subscriber registry, and
the snapshot + registration must happen atomically relative to the
live event stream. The driver invokes this method on the same task
that emits events, at a safe point between step polls, so every event
is either reflected in the snapshot or broadcast to the newly
registered subscriber afterwards — never both, never neither. Handing
the snapshot to another task to do the registration would reopen that
race.
Dyn Compatibility§
This trait is dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".