Skip to main content

ThreadObserver

Trait ThreadObserver 

Source
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_event is 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 from on_subscribe therefore gets exactly-once delivery for free: an event is either already reflected in the ReplaySnapshot a 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 StateStore transition.

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§

Source

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§

Source

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§

Source

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".

Implementors§