Struct ConversationWatcher 

pub struct ConversationWatcher { /* private fields */ }

Watches a conversation for new entries.

Tracks which entries have been seen (by UUID) and only returns new entries on subsequent polls.

Uses read_segment (single-file) internally — the watcher tails individual files and follows rotations via ChainIndex.

Example

use toolpath_claude::{ClaudeConvo, ConversationWatcher};

let manager = ClaudeConvo::new();
let mut watcher = ConversationWatcher::new(
    manager,
    "/path/to/project".to_string(),
    "session-uuid".to_string(),
);

// First poll returns all existing entries
let entries = watcher.poll().unwrap();
println!("Initial entries: {}", entries.len());

// Subsequent polls return only new entries
loop {
    std::thread::sleep(std::time::Duration::from_secs(1));
    let new_entries = watcher.poll().unwrap();
    for entry in new_entries {
        println!("New entry: {:?}", entry.uuid);
    }
}

Implementations

impl ConversationWatcher

pub fn new(manager: ClaudeConvo, project: String, session_id: String) -> Self

Creates a new watcher for the given conversation.

pub fn with_role_filter(self, role: MessageRole) -> Self

Sets a role filter - only entries with this role will be returned.

pub fn project(&self) -> &str

Returns the project path being watched.

pub fn session_id(&self) -> &str

Returns the session ID being watched.

pub fn seen_count(&self) -> usize

Returns the number of entries that have been seen.

pub fn poll(&mut self) -> Result<Vec<ConversationEntry>>

Polls for new conversation entries.

On the first call, returns all existing entries (optionally filtered by role). On subsequent calls, returns only entries that haven’t been seen before.

When the current session has been rotated to a successor file, the watcher automatically follows the chain and returns entries from the new file. Call Self::take_pending_rotations after poll to check whether a rotation occurred.

pub fn poll_with_full( &mut self, ) -> Result<(Conversation, Vec<ConversationEntry>)>

Polls and returns the full conversation along with just the new entries.

Useful when you need both the full state and the delta. Follows session rotations the same way Self::poll does.

pub fn reset(&mut self)

Resets the watcher, clearing all seen UUIDs and rotation state.

The next poll will return all entries as if it were the first call. Does not revert session_id — if a rotation was already followed, the watcher stays on the current (latest) session.

pub fn mark_seen(&mut self, entries: &[ConversationEntry])

Pre-marks entries as seen without returning them.

Useful for initializing the watcher to only return future entries.

pub fn skip_existing(&mut self) -> Result<usize>

Skips existing entries - next poll will only return new entries.

pub fn take_pending_rotations(&mut self) -> Vec<(String, String)>

Returns all rotations detected during the last poll(), consuming them. Each entry is (from_session, to_session). Multi-hop chains produce multiple entries in traversal order.

Trait Implementations

impl ConversationWatcher for ConversationWatcher

Available on crate feature watcher only.

fn poll(&mut self) -> Result<Vec<WatcherEvent>>

Poll for new events since the last poll.

fn seen_count(&self) -> usize

Number of turns seen so far.

impl Debug for ConversationWatcher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.