feat: WatcherEvent convenience methods and provider-namespaced extras

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the Toolpath workspace are documented here.
 
+## 0.5.0 — toolpath-convo / 0.6.2 — toolpath-claude
+
+### toolpath-convo 0.5.0
+
+- Added `WatcherEvent::as_turn()` — returns the `Turn` payload for both `Turn` and `TurnUpdated` variants
+- Added `WatcherEvent::as_progress()` — returns `(kind, data)` for `Progress` events
+- Added `WatcherEvent::is_update()` — returns `true` only for `TurnUpdated`
+- Added `WatcherEvent::turn_id()` — returns the turn ID for turn-carrying variants
+- Added dispatch loop example to `WatcherEvent` rustdoc
+
+### toolpath-claude 0.6.2
+
+- `to_turn()` now populates `Turn.extra["claude"]` with provider-specific metadata from `ConversationEntry.extra` (e.g. `subtype`, `data`), enabling trait-only consumers to access state-inference signals without importing provider types
+- `WatcherEvent::Progress` events now include the full entry payload under `data["claude"]`, carrying fields like `data.type`, `data.hookName`, `data.agentId`, and `data.message` that were previously discarded
+- Both changes are additive — previously-empty fields are now populated; no existing behavior changes
+- Thanks to the crabcity maintainers for the detailed gap analysis
+
 ## 0.6.1 — toolpath-claude
 
 ### toolpath-claude 0.6.1

CLAUDE.md

@@ -18,7 +18,7 @@ crates/
   toolpath-dot/                 # Graphviz DOT rendering
   toolpath-cli/                 # unified CLI (binary: path)
 schema/toolpath.schema.json     # JSON Schema for the format
-examples/*.json                 # 11 example documents (step, path, graph)
+examples/*.json                 # 12 example documents (step, path, graph)
 RFC.md                          # full format specification
 FAQ.md                          # design rationale, FAQ, and open questions
 ```
@@ -123,3 +123,4 @@ Build the site after changes: `cd site && pnpm run build` (should produce 7 page
 - The git derivation (`toolpath-git`) uses `git2` (libgit2 bindings), not shelling out to git
 - Claude conversation data lives in `~/.claude/projects/` as JSONL files; `toolpath-claude` reads these directly
 - `toolpath-claude` follows session chains by default — Claude Code rotates JSONL files on context overflow; `read_conversation` merges segments, `list_conversations` returns chain heads. `read_segment`/`list_segments` for single-file access. `ChainIndex` makes this incremental.
+- Provider-specific extras convention: `Turn.extra` and `WatcherEvent::Progress.data` use provider-namespaced keys (e.g. `extra["claude"]`). `toolpath-claude` populates `Turn.extra["claude"]` from `ConversationEntry.extra` and `Progress.data["claude"]` from the full entry payload. This lets trait-only consumers access provider metadata (like `subtype` for state inference) without importing provider types.

Cargo.toml

@@ -15,9 +15,9 @@ license = "Apache-2.0"
 
 [workspace.dependencies]
 toolpath = { version = "0.1.5", path = "crates/toolpath" }
-toolpath-convo = { version = "0.4.0", path = "crates/toolpath-convo" }
+toolpath-convo = { version = "0.5.0", path = "crates/toolpath-convo" }
 toolpath-git = { version = "0.1.3", path = "crates/toolpath-git" }
-toolpath-claude = { version = "0.6.1", path = "crates/toolpath-claude", default-features = false }
+toolpath-claude = { version = "0.6.2", path = "crates/toolpath-claude", default-features = false }
 toolpath-dot = { version = "0.1.2", path = "crates/toolpath-dot" }
 
 serde = { version = "1.0", features = ["derive"] }

crates/toolpath-claude/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "toolpath-claude"
-version = "0.6.1"
+version = "0.6.2"
 edition.workspace = true
 license.workspace = true
 repository = "https://github.com/empathic/toolpath"

crates/toolpath-claude/README.md

@@ -136,10 +136,20 @@ follows up with `WatcherEvent::TurnUpdated` when tool results arrive:
 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 { .. } => {}
+    match &event {
+        WatcherEvent::Turn(turn) => ui.add_turn(turn),
+        WatcherEvent::TurnUpdated(turn) => ui.replace_turn(turn),
+        WatcherEvent::Progress { kind, data } => {
+            match kind.as_str() {
+                "session_rotated" => ui.notify_rotation(&data["from"], &data["to"]),
+                _ => {
+                    // Provider-specific progress data under data["claude"]
+                    if let Some(claude) = data.get("claude") {
+                        ui.show_progress(kind, claude);
+                    }
+                }
+            }
+        }
     }
 }
 ```
@@ -179,6 +189,24 @@ cache read, cache write) into a single aggregate.
 `ConversationView.files_changed` lists all files mutated during the session
 (deduplicated, first-touch order), derived from `FileWrite`-categorized tool inputs.
 
+**Provider-specific metadata** — Claude log entries often carry extra fields
+(e.g. `subtype`, `data`) that don't map to the common `Turn` schema. These are
+forwarded into `Turn.extra["claude"]` so trait-only consumers can access them
+without importing Claude-specific types:
+
+```rust,ignore
+// State inference from provider metadata
+if let Some(claude) = turn.extra.get("claude") {
+    if claude.get("subtype").and_then(|v| v.as_str()) == Some("init") {
+        // This is a session initialization entry
+    }
+}
+```
+
+For `WatcherEvent::Progress` events, the full entry payload is similarly
+available under `data["claude"]` — carrying fields like `data.type`,
+`data.hookName`, `data.agentId`, and `data.message`.
+
 See [`toolpath-convo`](https://crates.io/crates/toolpath-convo) for the full trait and type definitions.
 
 ## Part of Toolpath

crates/toolpath-claude/src/lib.rs

@@ -610,14 +610,14 @@ mod tests {
         ).unwrap();
 
         // session-b: successor of a (bridge entry points to a)
-        let b = vec![
+        let b = [
             r#"{"uuid":"b0","type":"user","timestamp":"2024-01-01T01:00:00Z","sessionId":"session-a","message":{"role":"user","content":"Bridge"}}"#,
             r#"{"uuid":"b1","type":"user","timestamp":"2024-01-01T01:00:01Z","sessionId":"session-b","message":{"role":"user","content":"Middle"}}"#,
         ];
         fs::write(project_dir.join("session-b.jsonl"), b.join("\n")).unwrap();
 
         // session-c: successor of b
-        let c = vec![
+        let c = [
             r#"{"uuid":"c0","type":"user","timestamp":"2024-01-01T02:00:00Z","sessionId":"session-b","message":{"role":"user","content":"Bridge"}}"#,
             r#"{"uuid":"c1","type":"user","timestamp":"2024-01-01T02:00:01Z","sessionId":"session-c","message":{"role":"user","content":"End"}}"#,
         ];