OpenClaw provider: format docs, toolpath-openclaw crate, CLI wiring, real-session validation

CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to the Toolpath workspace are documented here.
 
+## toolpath-convo 0.13.0: typed round-trip fidelity fields — 2026-07-08
+
+Adds typed IR homes for cross-provider replay-fidelity data that providers
+previously had to drop (no provider-namespaced extras exist on the IR by
+design): `Turn.thinking_signature` / `Turn.text_signature` (opaque
+reasoning/text replay signatures — Anthropic thinking `signature`,
+OpenClaw `thinkingSignature`/`textSignature`), `Turn.response_model`
+(concrete served model under alias/auto routing), `Turn.marker`
+(`ConversationMarker::Compaction` / `BranchSummary` with
+`first_kept_id`/`tokens_before`/file lists/`from_hook` so structural
+boundaries survive projection), and
+`ToolInvocation.thought_signature`/`execution_mode`. All optional,
+serde-defaulted, written/read by the shared `derive_path` /
+`extract_conversation` (new `conversation.append` keys are valid under the
+permissive kind v1.1.0 schema; a future kind revision will document them).
+
+`toolpath-openclaw` uses all of them: signatures, `responseId`
+(→ `Turn.group_id`, the per-response accounting id), `responseModel`,
+and compaction/branch markers now survive session → Path → session
+round-trips byte-faithfully; `totalTokens` re-emits with the observed
+`input+output+cacheRead+cacheWrite` convention. Also fixes a real
+double-counting bug found in captured data: OpenClaw's final assembled
+reply after a `sessions_yield` carries run-cumulative usage with no
+`responseId`; the provider now detects that aggregate row (exact
+field-wise sum match, native files only) and refuses to stamp it onto a
+step, keeping session totals single-counted.
+
+## toolpath-openclaw 0.1.0: new provider (derive + inception) — 2026-07-08
+
+New crate `toolpath-openclaw`: reads OpenClaw's multi-channel agent-session
+JSONL (`~/.openclaw/agents/<id>/sessions/`, format v3), derives `Path`
+documents with channel-aware `human:<channel>/<peerId>` actors recovered
+from the `sessions.json` routing key, and projects/incepts a `Path` back
+onto disk (transcript + routing entry) that a **running** OpenClaw gateway
+adopts without restart — verified live. Wired through the `path` CLI
+(`p import/list/show/export openclaw`, `share`, and "inception+" `resume`
+that skips exec when a gateway is already listening). Validated against
+real sessions captured from the official Docker image (v2026.6.11),
+committed as `test-fixtures/openclaw/` and wired into the cross-harness
+matrix (all cells pass). File changes are structural only — OpenClaw
+stores no diffs.
+
+## toolpath-convo 0.12.0: session-level `user_actor` override — 2026-06-30
+
+Adds `DeriveConfig.user_actor: Option<String>` so a provider can set a
+session-level actor string for user turns (e.g. a channel-aware
+`human:whatsapp/<peerId>`) instead of the default `human:user`. Additive
+and backward-compatible — existing callers using `..Default::default()`
+are unaffected. Enables the multi-channel human identity in the new
+`toolpath-openclaw` provider.
+
 ## Token usage: once per message, with per-step attribution + kind v1.1.0 — 2026-06-17
 
 Fixes token over-counting in derived documents (~3× output-token

Cargo.toml

@@ -9,9 +9,10 @@ members = [
     "crates/toolpath-codex",
     "crates/toolpath-opencode",
     "crates/toolpath-cursor",
+    "crates/toolpath-pi",
+    "crates/toolpath-openclaw",
     "crates/toolpath-dot",
     "crates/toolpath-md",
-    "crates/toolpath-pi",
     "crates/pathbase-client",
     "crates/path-cli",
 ]
@@ -24,7 +25,7 @@ license = "Apache-2.0"
 
 [workspace.dependencies]
 toolpath = { version = "0.7.0", path = "crates/toolpath" }
-toolpath-convo = { version = "0.11.0", path = "crates/toolpath-convo" }
+toolpath-convo = { version = "0.13.0", path = "crates/toolpath-convo" }
 toolpath-git = { version = "0.6.0", path = "crates/toolpath-git" }
 toolpath-claude = { version = "0.12.0", path = "crates/toolpath-claude", default-features = false }
 toolpath-gemini = { version = "0.6.0", path = "crates/toolpath-gemini", default-features = false }
@@ -35,6 +36,7 @@ toolpath-github = { version = "0.6.0", path = "crates/toolpath-github" }
 toolpath-dot = { version = "0.5.0", path = "crates/toolpath-dot" }
 toolpath-md = { version = "0.7.0", path = "crates/toolpath-md" }
 toolpath-pi = { version = "0.6.0", path = "crates/toolpath-pi" }
+toolpath-openclaw = { version = "0.1.0", path = "crates/toolpath-openclaw" }
 path-cli = { version = "0.14.0", path = "crates/path-cli" }
 pathbase-client = { version = "0.2.0", path = "crates/pathbase-client" }
 

README.md

@@ -56,6 +56,7 @@ crates/
   toolpath-opencode/  Derive from opencode SQLite databases
   toolpath-cursor/    Derive from Cursor (IDE) state.vscdb bubble store
   toolpath-pi/        Derive from Pi (pi.dev) agent sessions
+  toolpath-openclaw/  Derive from OpenClaw agent-session logs
   toolpath-dot/       Graphviz DOT visualization
   toolpath-md/        Markdown rendering for LLM consumption
   pathbase-client/    Progenitor-derived typed client for the Pathbase HTTP API

crates/path-cli/Cargo.toml

@@ -45,6 +45,7 @@ toolpath-codex = { workspace = true }
 toolpath-opencode = { workspace = true }
 toolpath-cursor = { workspace = true }
 toolpath-pi = { workspace = true }
+toolpath-openclaw = { workspace = true }
 toolpath-convo = { workspace = true }
 toolpath-github = { workspace = true }
 pathbase-client = { workspace = true }
@@ -69,6 +70,7 @@ toolpath-claude = { workspace = true }
 toolpath-gemini = { workspace = true }
 toolpath-codex = { workspace = true }
 toolpath-pi = { workspace = true }
+toolpath-openclaw = { workspace = true }
 
 [features]
 default = ["embedded-picker"]

crates/path-cli/src/cmd_export.rs

@@ -79,6 +79,24 @@ pub enum ExportTarget {
         #[arg(short, long, conflicts_with = "project")]
         output: Option<PathBuf>,
     },
+    /// Project ("incept") a toolpath document into an OpenClaw session
+    Openclaw {
+        /// Input: cache id (e.g. `claude-abc`) or path to a toolpath JSON file
+        #[arg(short, long)]
+        input: String,
+
+        /// Working directory to record in the session header. With this flag,
+        /// the session is incepted into `~/.openclaw/agents/<agent>/sessions/`
+        /// (plus a `sessions.json` routing entry) so a running OpenClaw
+        /// instance can pick it up. Defaults to cwd when neither --project nor
+        /// --output is given.
+        #[arg(short, long)]
+        project: Option<PathBuf>,
+
+        /// Output JSONL to this file. Mutually exclusive with --project.
+        #[arg(short, long, conflicts_with = "project")]
+        output: Option<PathBuf>,
+    },
     /// Project a toolpath document into a Codex CLI session
     Codex {
         /// Input: cache id (e.g. `claude-abc`) or path to a toolpath JSON file
@@ -213,6 +231,11 @@ pub fn run(target: ExportTarget) -> Result<()> {
             project,
             output,
         } => run_pi(input, project, output),
+        ExportTarget::Openclaw {
+            input,
+            project,
+            output,
+        } => run_openclaw(input, project, output),
         ExportTarget::Codex {
             input,
             project,
@@ -375,6 +398,95 @@ pub(crate) fn project_pi(
     Ok(session.header.id)
 }
 
+/// Incept a Path into the real OpenClaw state dir (`~/.openclaw`), recording
+/// `cwd` in the header. Returns the session id. Used by `path resume`.
+pub(crate) fn project_openclaw(
+    path: &toolpath::v1::Path,
+    cwd: &std::path::Path,
+) -> Result<String> {
+    let (projector, session) = build_openclaw(path, &cwd.to_string_lossy())?;
+    let state_dir = toolpath_openclaw::PathResolver::new()
+        .state_dir()
+        .to_path_buf();
+    projector
+        .write_session(&session, &state_dir)
+        .map_err(|e| anyhow::anyhow!("OpenClaw inception failed: {}", e))?;
+    Ok(session.header.id)
+}
+
+/// Build an OpenClaw projector (channel/peer/agent recovered from
+/// `meta.extra["openclaw"]`) plus the projected session.
+fn build_openclaw(
+    path: &toolpath::v1::Path,
+    cwd: &str,
+) -> Result<(
+    toolpath_openclaw::project::OpenClawProjector,
+    toolpath_openclaw::OpenClawSession,
+)> {
+    use toolpath_convo::ConversationProjector;
+    let view = toolpath_convo::extract_conversation(path);
+    let mut projector =
+        toolpath_openclaw::project::OpenClawProjector::new().with_cwd(cwd.to_string());
+    if let Some(extra) = path.meta.as_ref().and_then(|m| m.extra.get("openclaw")) {
+        projector = projector.with_meta_extra(extra);
+    }
+    let session = projector
+        .project(&view)
+        .map_err(|e| anyhow::anyhow!("Projection failed: {}", e))?;
+    if session.header.id.is_empty() {
+        anyhow::bail!("Projected session has no id");
+    }
+    Ok((projector, session))
+}
+
+fn openclaw_session_to_jsonl(session: &toolpath_openclaw::OpenClawSession) -> Result<String> {
+    let mut out = String::new();
+    for entry in &session.entries {
+        out.push_str(&serde_json::to_string(entry)?);
+        out.push('\n');
+    }
+    Ok(out)
+}
+
+fn run_openclaw(input: String, project: Option<PathBuf>, output: Option<PathBuf>) -> Result<()> {
+    #[cfg(target_os = "emscripten")]
+    {
+        let _ = (input, project, output);
+        anyhow::bail!("'path p export openclaw' requires a native environment");
+    }
+    #[cfg(not(target_os = "emscripten"))]
+    {
+        let path = load_path_doc(&input)?;
+        match (project, output) {
+            (Some(project_dir), None) => {
+                let id = project_openclaw(&path, &project_dir)?;
+                let state = toolpath_openclaw::PathResolver::new()
+                    .state_dir()
+                    .to_path_buf();
+                eprintln!("Incepted OpenClaw session {id} into {}", state.display());
+                eprintln!();
+                eprintln!("A running OpenClaw instance routes it via sessions.json.");
+            }
+            (None, Some(out_path)) => {
+                let cwd = std::env::current_dir()
+                    .map(|p| p.to_string_lossy().into_owned())
+                    .unwrap_or_else(|_| "/".to_string());
+                let (_projector, session) = build_openclaw(&path, &cwd)?;
+                let jsonl = openclaw_session_to_jsonl(&session)?;
+                std::fs::write(&out_path, &jsonl)
+                    .with_context(|| format!("write {}", out_path.display()))?;
+                eprintln!("Wrote {} bytes to {}", jsonl.len(), out_path.display());
+            }
+            (None, None) => {
+                let (_projector, session) = build_openclaw(&path, "/")?;
+                print!("{}", openclaw_session_to_jsonl(&session)?);
+            }
+            (Some(_), Some(_)) => unreachable!("clap enforces conflicts_with"),
+        }
+        Ok(())
+    }
+}
+
 fn run_claude(input: String, project: Option<PathBuf>, output: Option<PathBuf>) -> Result<()> {
     #[cfg(target_os = "emscripten")]
     {