toolpath-convo

Provider-agnostic conversation types and traits for AI coding tools.

This crate defines a common vocabulary for representing conversations from any AI coding assistant (Claude, Codex, OpenCode, etc.) without coupling consumer code to provider-specific data formats.

Write your conversation analysis once, swap providers without changing a line.

Overview

Types define the common data model:

Traits define how providers expose their data:

Usage

use toolpath_convo::{ConversationView, ConversationProvider, Role, ToolCategory};

// Provider crates implement ConversationProvider.
// Consumer code works against the trait:
fn show_conversation(provider: &dyn ConversationProvider) {
    let view = provider.load_conversation("/path/to/project", "session-id")
        .unwrap();

    if let Some(title) = view.title(80) {
        println!("# {}", title);
    }

    // Session-level summary
    if let Some(usage) = &view.total_usage {
        println!("Tokens: {:?} in / {:?} out", usage.input_tokens, usage.output_tokens);
    }
    println!("Files changed: {:?}", view.files_changed);

    for turn in &view.turns {
        println!("[{}] {}", turn.role, turn.text);

        // Environment context
        if let Some(env) = &turn.environment {
            println!("  cwd: {:?}, branch: {:?}", env.working_dir, env.vcs_branch);
        }

        // Tool classification
        for tool_use in &turn.tool_uses {
            println!("  {} ({:?})", tool_use.name, tool_use.category);
        }

        // Sub-agent delegations
        for d in &turn.delegations {
            println!("  delegated: {}", d.prompt);
            if let Some(result) = &d.result {
                println!("    -> {}", result);
            }
        }
    }
}

Tool classification

ToolCategory is toolpath's own ontology for what a tool invocation does, independent of provider-specific naming. Provider crates map their tool names into these categories; None means the tool isn't recognized.

Consumers can filter by category without knowing provider tool vocabularies:

let writes: Vec<_> = turn.tool_uses.iter()
    .filter(|t| t.category == Some(ToolCategory::FileWrite))
    .collect();

Watching

Dispatch on WatcherEvent with match — three variants, exhaustive:

use toolpath_convo::{ConversationWatcher, WatcherEvent};

for event in watcher.poll()? {
    match &event {
        WatcherEvent::Turn(turn) => ui.add_turn(turn),
        WatcherEvent::TurnUpdated(turn) => ui.replace_turn(turn),
        WatcherEvent::Progress { kind, data } => ui.show_progress(kind, data),
    }
}

Convenience methods (as_turn(), as_progress(), is_update(), turn_id()) are available for cases where the distinction between Turn and TurnUpdated collapses — e.g. a formatting pipeline that takes a turn + flag:

// When Turn/TurnUpdated go through the same path:
if let Some(turn) = event.as_turn() {
    format_turn(turn, event.is_update());
}

// Keying/dedup without matching two variants:
if let Some(id) = event.turn_id() {
    seen.insert(id);
}

Provider-specific metadata lives in Turn.extra, namespaced by provider (e.g. turn.extra["claude"]). This keeps the common schema clean while giving consumers opt-in access to provider internals.

Provider implementations

Part of Toolpath

This crate is part of the Toolpath workspace. See also:

• toolpath -- core provenance types and query API
• toolpath-claude -- Claude conversation provider
• toolpath-git -- derive from git history
• toolpath-dot -- Graphviz DOT rendering
• toolpath-cli -- unified CLI (cargo install toolpath-cli)
• RFC -- full format specification