feat: add toolpath-convo crate for provider-agnostic conversation abstraction

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to the Toolpath workspace are documented here.
 
+## 0.1.0 — toolpath-convo / 0.1.3 — toolpath-claude
+
+### toolpath-convo 0.1.0
+
+- New crate: provider-agnostic conversation types and traits for AI coding tools
+- Types: `Turn`, `Role`, `ConversationView`, `ConversationMeta`, `TokenUsage`, `ToolInvocation`, `ToolResult`, `WatcherEvent`
+- Traits: `ConversationProvider` (list/load conversations), `ConversationWatcher` (poll for updates)
+- Enables consumer apps to code against a common conversation model instead of provider-specific types
+
+### toolpath-claude 0.1.3
+
+- Added convenience methods on `Message`: `text()`, `thinking()`, `tool_uses()`, `is_user()`, `is_assistant()`, `is_role()`
+- Added convenience methods on `ConversationEntry`: `text()`, `role()`, `thinking()`, `tool_uses()`, `stop_reason()`, `model()`
+- Added convenience methods on `Conversation`: `title(max_len)`, `first_user_text()`
+- Implemented `toolpath_convo::ConversationProvider` for `ClaudeConvo`
+- Implemented `toolpath_convo::ConversationWatcher` for sync `ConversationWatcher`
+- Added `provider::to_view()` and `provider::to_turn()` for direct conversion
+- New dependency: `toolpath-convo`
+
 ## 0.1.4 — toolpath / 0.2.0 — toolpath-cli
 
 ### toolpath 0.1.4

CLAUDE.md

@@ -12,6 +12,7 @@ Three core objects: **Step** (a single change), **Path** (a sequence of steps, e
 Cargo.toml                      # workspace root (edition 2024, resolver 2)
 crates/
   toolpath/                     # core types, builders, serde, query API
+  toolpath-convo/               # provider-agnostic conversation types and traits
   toolpath-git/                 # derive from git repos (git2)
   toolpath-claude/              # derive from Claude conversation logs
   toolpath-dot/                 # Graphviz DOT rendering
@@ -27,12 +28,13 @@ FAQ.md                          # design rationale, FAQ, and open questions
 ```
 toolpath-cli (binary: path)
  ├── toolpath           (core types)
+ ├── toolpath-convo     (conversation abstraction)
  ├── toolpath-git     → toolpath
- ├── toolpath-claude  → toolpath
+ ├── toolpath-claude  → toolpath, toolpath-convo
  └── toolpath-dot     → toolpath
 ```
 
-No cross-dependencies between satellite crates. `toolpath` is the sole shared foundation.
+No cross-dependencies between satellite crates except `toolpath-claude → toolpath-convo`.
 
 ## Build and test
 

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
     "crates/toolpath",
+    "crates/toolpath-convo",
     "crates/toolpath-git",
     "crates/toolpath-claude",
     "crates/toolpath-dot",
@@ -14,6 +15,7 @@ license = "Apache-2.0"
 
 [workspace.dependencies]
 toolpath = { version = "0.1.5", path = "crates/toolpath" }
+toolpath-convo = { version = "0.1.0", path = "crates/toolpath-convo" }
 toolpath-git = { version = "0.1.3", path = "crates/toolpath-git" }
 toolpath-claude = { version = "0.1.2", path = "crates/toolpath-claude", default-features = false }
 toolpath-dot = { version = "0.1.2", path = "crates/toolpath-dot" }

README.md

@@ -41,6 +41,7 @@ This installs a binary called `path`.
 ```
 crates/
   toolpath/           Core types, builders, query API
+  toolpath-convo/     Provider-agnostic conversation types and traits
   toolpath-git/       Derive from git repository history
   toolpath-claude/    Derive from Claude conversation logs
   toolpath-dot/       Graphviz DOT visualization

crates/toolpath-claude/Cargo.toml

@@ -14,6 +14,7 @@ watcher = ["dep:notify", "dep:tokio"]
 
 [dependencies]
 toolpath = { workspace = true }
+toolpath-convo = { workspace = true }
 anyhow = { workspace = true }
 chrono = { workspace = true }
 serde = { workspace = true }

crates/toolpath-claude/README.md

@@ -102,11 +102,31 @@ while let Some(entries) = handle.recv().await {
 |---|---|---|
 | `watcher` | yes | Filesystem watching via `notify` + `tokio` |
 
+## Provider-agnostic usage
+
+This crate implements `toolpath_convo::ConversationProvider`, so consumers can
+code against the provider-agnostic types instead of Claude-specific structures:
+
+```rust,ignore
+use toolpath_claude::ClaudeConvo;
+use toolpath_convo::ConversationProvider;
+
+let provider = ClaudeConvo::new();
+let view = provider.load_conversation("/path/to/project", "session-id")?;
+
+for turn in &view.turns {
+    println!("[{}] {}: {}", turn.timestamp, turn.role, turn.text);
+}
+```
+
+See [`toolpath-convo`](https://crates.io/crates/toolpath-convo) for the full trait and type definitions.
+
 ## Part of Toolpath
 
 This crate is part of the [Toolpath](https://github.com/empathic/toolpath) workspace. See also:
 
 - [`toolpath`](https://crates.io/crates/toolpath) -- core types and query API
+- [`toolpath-convo`](https://crates.io/crates/toolpath-convo) -- provider-agnostic conversation abstraction
 - [`toolpath-git`](https://crates.io/crates/toolpath-git) -- derive from git history
 - [`toolpath-dot`](https://crates.io/crates/toolpath-dot) -- Graphviz DOT rendering
 - [`toolpath-cli`](https://crates.io/crates/toolpath-cli) -- unified CLI (`cargo install toolpath-cli`)

crates/toolpath-claude/src/lib.rs

@@ -6,6 +6,7 @@ pub mod derive;
 pub mod error;
 pub mod io;
 pub mod paths;
+pub mod provider;
 pub mod query;
 pub mod reader;
 pub mod types;
@@ -21,7 +22,7 @@ pub use query::{ConversationQuery, HistoryQuery};
 pub use reader::ConversationReader;
 pub use types::{
     CacheCreation, ContentPart, Conversation, ConversationEntry, ConversationMetadata,
-    HistoryEntry, Message, MessageContent, MessageRole, ToolResultContent, Usage,
+    HistoryEntry, Message, MessageContent, MessageRole, ToolResultContent, ToolUseRef, Usage,
 };
 #[cfg(feature = "watcher")]
 pub use watcher::ConversationWatcher;