Crate toolpath_convo 

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:

Type	What it represents
Turn	A single conversational turn (text, thinking, tool uses, model, tokens, environment, delegations)
Role	Who produced the turn: User, Assistant, System, Other(String)
ConversationView	A complete conversation: ordered turns, timestamps, aggregate usage, files changed
ConversationMeta	Lightweight metadata (no turns loaded)
ToolInvocation	A tool call within a turn, with optional ToolCategory classification
ToolResult	The result of a tool call
ToolCategory	Toolpath’s classification ontology: FileRead, FileWrite, FileSearch, Shell, Network, Delegation
TokenUsage	Input/output/cache token counts
EnvironmentSnapshot	Working directory and VCS branch/revision at time of a turn
DelegatedWork	A sub-agent delegation: prompt, nested turns, result
WatcherEvent	A Turn (new), TurnUpdated (enriched with tool results), or Progress event

Traits define how providers expose their data:

Trait	What it does
ConversationProvider	List and load conversations from any source
ConversationWatcher	Poll for new conversational events

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.

Category	Meaning
FileRead	Read a file — no side effects
FileWrite	Write, edit, create, or delete a file
FileSearch	Search or discover files by name or content pattern
Shell	Shell or terminal command execution
Network	Web fetch, search, API call
Delegation	Spawn a sub-agent or delegate work

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();

Provider implementations

Provider	Crate
Claude Code	toolpath-claude

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

Structs

ConversationMeta

Lightweight metadata for a conversation (no turns loaded).

ConversationView

A complete conversation from any provider.

DelegatedWork

A sub-agent delegation: a turn that spawned child work.

EnvironmentSnapshot

Snapshot of the working environment when a turn was produced.

SessionLink

A link between two session segments.

TokenUsage

Token usage for a single turn.

ToolInvocation

A tool invocation within a turn.

ToolResult

The result of a tool invocation.

Turn

A single turn in a conversation, from any provider.

Enums

ConvoError

Errors from conversation provider operations.

Role

Who produced a turn.

SessionLinkKind

Why two session files are linked.

ToolCategory

Toolpath’s classification of what a tool invocation does.

WatcherEvent

Events emitted by a ConversationWatcher.

Traits

ConversationProvider

Trait for converting provider-specific conversation data into the generic ConversationView.

ConversationWatcher

Trait for polling conversation updates from any provider.

Type Aliases

Result