feat(protocol): negotiate Trace v3 with v2 compatibility

Define Trace v3 wire types and generated schemas while keeping protocol 1.1 peers compatible with 1.0. Default record start still produces Trace v2, and only an explicit trace_version=3 request enables the new shape. Refs #90 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 13:01:23 +08:00 · 2026-08-23 21:26:39 +08:00
parent d05279f991
commit f98198949a
32 changed files with 2573 additions and 671 deletions
@@ -9,6 +9,7 @@ pub mod navigation;
 pub mod network;
 pub mod observation;
 pub mod record;
+pub mod record_v2;
 pub mod script;
 pub mod session;
 pub mod tabs;
@@ -1,35 +1,39 @@
 //! Semantic user-action recording (`tool.record_start` / `stop` / `await`).
 //!
-//! Trace v2 is a **record-only** log of user actions: what was clicked, filled,
-//! selected, and where navigation occurred. No LLM runs during recording, so
-//! variable-vs-constant classification is **not** stored — executing agents
-//! infer that at run time from raw values and control names.
+//! Trace v3 is a **state-action-state** chain: each step binds to page
+//! observations (VOM) captured before and after the action.

 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};

 use super::interaction::KeyModifier;

+pub use crate::record_v2::{
+    PageRef, SelectedOptionV2, StepCommonV2, StepEffectV2, StepV2, TargetDescriptorV2, TraceV2,
+};
+
+pub const TRACE_VERSION: u32 = 3;
+pub const TRACE_VERSION_V2: u32 = 2;
+pub const DEFAULT_TRACE_VERSION: u32 = 2;
+pub const VOM_FORMAT_VERSION: u32 = 1;
+
 // ---------------------------------------------------------------------------
 // Target
 // ---------------------------------------------------------------------------

-/// Stable semantic handle for an interacted element.
-///
-/// `name` and `nearby_label` are **untrusted page text**.
+/// Stable semantic handle for an interacted element within a page observation.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct TargetDescriptor {
+    #[serde(default, skip_serializing_if = "Option::is_none", rename = "ref")]
+    pub element_ref: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub role: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
-    pub tag: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub name_attr: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub placeholder: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub nearby_label: Option<String>,
+    pub ctx: Option<String>,
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub unmatched: bool,
 }

 // ---------------------------------------------------------------------------
@@ -42,15 +46,54 @@ pub struct TraceEntry {
    pub start_url: String,
 }

-/// Page context dictionary entry — referenced by steps via `page` id.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct PageRef {
+pub struct RecorderInfo {
+    pub bsk: String,
+    pub vom: u32,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum StopReason {
+    UserFinish,
+    CliStop,
+}
+
+/// Page observation dictionary entry — referenced by steps via `state` / `result.state`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TraceState {
    pub id: String,
    pub url: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
+    /// Wire-only: full page observation (front matter + VOM body + annotations).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub body: Option<String>,
+    /// Disk-only: filename under the bundle `pages/` directory.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub page: Option<String>,
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub truncated: bool,
 }

+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct StepResult {
+    pub state: String,
+}
+
+/// Fields shared by every step variant (flattened in JSON).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct StepCommon {
+    pub id: u32,
+    /// Observation id immediately before this action.
+    pub state: String,
+    pub result: StepResult,
+}
+
+// ---------------------------------------------------------------------------
+// Step op-specific payloads
+// ---------------------------------------------------------------------------
+
 /// One selected option (`select` op).
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct SelectedOption {
@@ -59,27 +102,26 @@ pub struct SelectedOption {
    pub label: Option<String>,
 }

-/// Observed navigation after a step (objective fact only).
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct StepEffect {
-    /// Reference into `pages[]` for the destination page.
-    pub navigated_to: String,
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum NavigationCause {
+    UserTyped,
+    Link,
+    FormSubmit,
+    Reload,
+    History,
+    Script,
+    Browser,
 }

-/// Fields shared by every step variant (flattened in JSON).
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct StepCommon {
-    pub id: u32,
-    /// Reference into `pages[]`.
-    pub page: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub effect: Option<StepEffect>,
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum FillCommit {
+    Enter,
+    Suggestion,
+    Blur,
 }

-// ---------------------------------------------------------------------------
-// Step op-specific payloads
-// ---------------------------------------------------------------------------
-
 /// One recorded user action — discriminated union by `op`.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 #[serde(tag = "op", rename_all = "snake_case")]
@@ -88,6 +130,7 @@ pub enum Step {
        #[serde(flatten)]
        common: StepCommon,
        to: String,
+        cause: NavigationCause,
    },
    Click {
        #[serde(flatten)]
@@ -104,13 +147,15 @@ pub enum Step {
        common: StepCommon,
        target: TargetDescriptor,
        value: String,
-        #[serde(default, skip_serializing_if = "Option::is_none")]
-        redacted: Option<bool>,
+        commit: FillCommit,
+        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+        redacted: bool,
    },
    Select {
        #[serde(flatten)]
        common: StepCommon,
        target: TargetDescriptor,
+        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        selection: Vec<SelectedOption>,
    },
    Press {
@@ -122,6 +167,10 @@ pub enum Step {
        #[serde(default, skip_serializing_if = "Option::is_none")]
        target: Option<TargetDescriptor>,
    },
+    Scroll {
+        #[serde(flatten)]
+        common: StepCommon,
+    },
 }

 // ---------------------------------------------------------------------------
@@ -131,15 +180,16 @@ pub enum Step {
 /// Persisted user-action trace exported by `tool.record_stop` / `await`.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct Trace {
-    /// RFC 3339 timestamp when recording stopped.
-    pub recorded_at: String,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub started_at: Option<String>,
-    /// Optional user-provided goal from `--purpose` (metadata only).
+    pub version: u32,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_at: Option<String>,
+    pub recorded_at: String,
+    pub stopped_by: StopReason,
    pub entry: TraceEntry,
-    pub pages: Vec<PageRef>,
+    pub recorder: RecorderInfo,
+    pub states: Vec<TraceState>,
    pub steps: Vec<Step>,
 }

@@ -156,6 +206,13 @@ pub struct RecordStartParams {
    pub url: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub purpose: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_page_tokens: Option<u32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub redact_values: Option<bool>,
+    /// Desired trace export format. Omitted ⇒ v2; `3` ⇒ state-linked v3 bundle.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub trace_version: Option<u32>,
 }

 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -169,9 +226,100 @@ pub struct RecordStopParams {
    pub session_id: String,
 }

+/// Wire trace payload — v2 (legacy `pages[]`) or v3 (`version: 3`, `states[]`).
+#[derive(Debug, Clone, PartialEq)]
+pub enum RecordedTrace {
+    V2(TraceV2),
+    V3(Trace),
+}
+
+impl RecordedTrace {
+    pub fn classify_value(v: &serde_json::Value) -> Result<Self, String> {
+        if let Some(ver) = v.get("version").and_then(|x| x.as_u64()) {
+            if ver == u64::from(TRACE_VERSION) {
+                return serde_json::from_value(v.clone())
+                    .map(RecordedTrace::V3)
+                    .map_err(|e| e.to_string());
+            }
+            return Err(format!("unsupported trace version {ver}"));
+        }
+        if v.get("pages").is_some() && v.get("states").is_none() {
+            return serde_json::from_value(v.clone())
+                .map(RecordedTrace::V2)
+                .map_err(|e| e.to_string());
+        }
+        if v.get("states").is_some() {
+            return serde_json::from_value(v.clone())
+                .map(RecordedTrace::V3)
+                .map_err(|e| e.to_string());
+        }
+        Err("ambiguous or unparseable trace".into())
+    }
+
+    pub fn is_v3(&self) -> bool {
+        matches!(self, RecordedTrace::V3(_))
+    }
+
+    pub fn as_v3(&self) -> Option<&Trace> {
+        match self {
+            RecordedTrace::V3(t) => Some(t),
+            RecordedTrace::V2(_) => None,
+        }
+    }
+
+    pub fn as_v2(&self) -> Option<&TraceV2> {
+        match self {
+            RecordedTrace::V2(t) => Some(t),
+            RecordedTrace::V3(_) => None,
+        }
+    }
+}
+
+impl Serialize for RecordedTrace {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        match self {
+            RecordedTrace::V2(t) => t.serialize(serializer),
+            RecordedTrace::V3(t) => t.serialize(serializer),
+        }
+    }
+}
+
+impl<'de> Deserialize<'de> for RecordedTrace {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let value = serde_json::Value::deserialize(deserializer)?;
+        Self::classify_value(&value).map_err(serde::de::Error::custom)
+    }
+}
+
+impl JsonSchema for RecordedTrace {
+    fn schema_name() -> String {
+        "RecordedTrace".into()
+    }
+
+    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::schema::Schema {
+        schemars::schema::SchemaObject {
+            subschemas: Some(Box::new(schemars::schema::SubschemaValidation {
+                one_of: Some(vec![
+                    generator.subschema_for::<TraceV2>(),
+                    generator.subschema_for::<Trace>(),
+                ]),
+                ..Default::default()
+            })),
+            ..Default::default()
+        }
+        .into()
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct RecordStopResult {
-    pub trace: Trace,
+    pub trace: RecordedTrace,
 }

 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -183,7 +331,7 @@ pub struct RecordAwaitParams {

 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct RecordAwaitResult {
-    pub trace: Trace,
+    pub trace: RecordedTrace,
 }

 // ---------------------------------------------------------------------------
@@ -195,81 +343,79 @@ mod tests {
    use super::*;
    use serde_json::json;

-    fn sample_common(id: u32) -> StepCommon {
+    fn sample_common(id: u32, state: &str, result_state: &str) -> StepCommon {
        StepCommon {
            id,
-            page: "p1".into(),
-            effect: None,
+            state: state.into(),
+            result: StepResult {
+                state: result_state.into(),
+            },
        }
    }

    fn sample_target() -> TargetDescriptor {
        TargetDescriptor {
+            element_ref: Some("e21".into()),
            role: Some("button".into()),
            name: Some("发布".into()),
-            tag: "button".into(),
-            name_attr: None,
-            placeholder: None,
-            nearby_label: None,
+            ctx: Some("金桔柠檬 6 号".into()),
+            unmatched: false,
        }
    }

    fn sample_trace() -> Trace {
        Trace {
-            recorded_at: "2026-07-17T09:01:10Z".into(),
-            started_at: Some("2026-07-17T09:00:00Z".into()),
-            purpose: Some("发布一篇文章".into()),
+            version: TRACE_VERSION,
+            purpose: Some("把草稿商品发布上架".into()),
+            started_at: Some("2026-08-10T02:10:41.080Z".into()),
+            recorded_at: "2026-08-10T02:12:55.360Z".into(),
+            stopped_by: StopReason::UserFinish,
            entry: TraceEntry {
-                start_url: "https://x.com/editor".into(),
+                start_url: "https://example.com/".into(),
            },
-            pages: vec![
-                PageRef {
-                    id: "p1".into(),
-                    url: "https://x.com/editor".into(),
-                    title: Some("写文章".into()),
+            recorder: RecorderInfo {
+                bsk: "0.1.10".into(),
+                vom: VOM_FORMAT_VERSION,
+            },
+            states: vec![
+                TraceState {
+                    id: "s1".into(),
+                    url: "https://example.com/".into(),
+                    title: Some("Example Domain".into()),
+                    body: None,
+                    page: Some("s1.vom.txt".into()),
+                    truncated: false,
                },
-                PageRef {
-                    id: "p2".into(),
-                    url: "https://x.com/p/99".into(),
-                    title: None,
+                TraceState {
+                    id: "s2".into(),
+                    url: "https://shop.example.com/products?status=draft".into(),
+                    title: Some("商品管理".into()),
+                    body: None,
+                    page: Some("s2.vom.txt".into()),
+                    truncated: false,
                },
            ],
            steps: vec![
-                Step::Fill {
-                    common: sample_common(1),
-                    target: TargetDescriptor {
-                        role: Some("textbox".into()),
-                        name: Some("标题".into()),
-                        tag: "input".into(),
-                        name_attr: None,
-                        placeholder: None,
-                        nearby_label: None,
-                    },
-                    value: "我的第一篇文章".into(),
-                    redacted: None,
+                Step::Navigate {
+                    common: sample_common(1, "s1", "s2"),
+                    to: "https://shop.example.com/products?status=draft".into(),
+                    cause: NavigationCause::UserTyped,
                },
-                Step::Select {
-                    common: sample_common(3),
+                Step::Fill {
+                    common: sample_common(2, "s2", "s2"),
                    target: TargetDescriptor {
-                        role: Some("combobox".into()),
-                        name: Some("分类".into()),
-                        tag: "select".into(),
-                        name_attr: None,
-                        placeholder: None,
-                        nearby_label: None,
+                        element_ref: Some("e12".into()),
+                        role: Some("textbox".into()),
+                        name: Some("搜索商品".into()),
+                        ctx: None,
+                        unmatched: false,
                    },
-                    selection: vec![SelectedOption {
-                        value: "tech".into(),
-                        label: Some("技术分享".into()),
-                    }],
+                    value: "金桔柠檬".into(),
+                    commit: FillCommit::Enter,
+                    redacted: false,
                },
                Step::Click {
-                    common: StepCommon {
-                        effect: Some(StepEffect {
-                            navigated_to: "p2".into(),
-                        }),
-                        ..sample_common(4)
-                    },
+                    common: sample_common(3, "s2", "s2"),
                    target: sample_target(),
                },
            ],
@@ -279,35 +425,37 @@ mod tests {
    #[test]
    fn step_click_round_trips() {
        let step = Step::Click {
-            common: sample_common(1),
+            common: sample_common(1, "s1", "s2"),
            target: sample_target(),
        };
        let v = serde_json::to_value(&step).unwrap();
        assert_eq!(v.get("op").and_then(|v| v.as_str()), Some("click"));
-        assert_eq!(v.get("page").and_then(|v| v.as_str()), Some("p1"));
-        assert!(v.get("key").is_none());
+        assert_eq!(v.get("state").and_then(|v| v.as_str()), Some("s1"));
+        assert_eq!(v["result"]["state"], "s2");
+        assert_eq!(v["target"]["ref"], "e21");
        let round: Step = serde_json::from_value(v).unwrap();
        assert_eq!(round, step);
    }

    #[test]
-    fn step_fill_with_raw_value_round_trips() {
+    fn step_fill_with_commit_round_trips() {
        let step = Step::Fill {
-            common: sample_common(2),
+            common: sample_common(2, "s2", "s3"),
            target: TargetDescriptor {
+                element_ref: Some("e12".into()),
                role: Some("textbox".into()),
-                name: Some("服务名称".into()),
-                tag: "input".into(),
-                name_attr: Some("serviceName".into()),
-                placeholder: None,
-                nearby_label: None,
+                name: Some("搜索商品".into()),
+                ctx: None,
+                unmatched: false,
            },
-            value: "my-svc".into(),
-            redacted: None,
+            value: "browser skill".into(),
+            commit: FillCommit::Enter,
+            redacted: false,
        };
        let v = serde_json::to_value(&step).unwrap();
        assert_eq!(v["op"], "fill");
-        assert_eq!(v["value"], "my-svc");
+        assert_eq!(v["commit"], "enter");
+        assert!(v.get("redacted").is_none());
        let round: Step = serde_json::from_value(v).unwrap();
        assert_eq!(round, step);
    }
@@ -315,17 +463,17 @@ mod tests {
    #[test]
    fn step_fill_password_is_redacted() {
        let step = Step::Fill {
-            common: sample_common(1),
+            common: sample_common(1, "s1", "s1"),
            target: TargetDescriptor {
+                element_ref: Some("e3".into()),
                role: Some("textbox".into()),
                name: Some("密码".into()),
-                tag: "input".into(),
-                name_attr: None,
-                placeholder: None,
-                nearby_label: None,
+                ctx: None,
+                unmatched: false,
            },
            value: "***".into(),
-            redacted: Some(true),
+            commit: FillCommit::Blur,
+            redacted: true,
        };
        let v = serde_json::to_value(&step).unwrap();
        assert_eq!(v["value"], "***");
@@ -333,131 +481,140 @@ mod tests {
    }

    #[test]
-    fn step_select_uses_object_array() {
-        let step = Step::Select {
-            common: sample_common(3),
-            target: TargetDescriptor {
-                role: Some("combobox".into()),
-                name: Some("分类".into()),
-                tag: "select".into(),
-                name_attr: None,
-                placeholder: None,
-                nearby_label: None,
-            },
-            selection: vec![SelectedOption {
-                value: "tech".into(),
-                label: Some("技术分享".into()),
-            }],
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["selection"][0]["value"], "tech");
-        assert_eq!(v["selection"][0]["label"], "技术分享");
-        let round: Step = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn step_navigate_round_trips() {
+    fn step_navigate_with_cause_round_trips() {
        let step = Step::Navigate {
-            common: sample_common(1),
+            common: sample_common(1, "s1", "s2"),
            to: "https://example.com".into(),
+            cause: NavigationCause::UserTyped,
        };
        let v = serde_json::to_value(&step).unwrap();
        assert_eq!(v["op"], "navigate");
-        assert_eq!(v["to"], "https://example.com");
+        assert_eq!(v["cause"], "user_typed");
        let round: Step = serde_json::from_value(v).unwrap();
        assert_eq!(round, step);
    }

    #[test]
-    fn step_press_with_modifiers_round_trips() {
-        let step = Step::Press {
-            common: StepCommon {
-                effect: Some(StepEffect {
-                    navigated_to: "p2".into(),
-                }),
-                ..sample_common(2)
-            },
-            key: "Enter".into(),
-            modifiers: Some(vec![KeyModifier::Ctrl, KeyModifier::Shift]),
-            target: Some(sample_target()),
-        };
-        let v = serde_json::to_value(&step).unwrap();
-        assert_eq!(v["key"], "Enter");
-        assert_eq!(v["modifiers"], json!(["ctrl", "shift"]));
-        assert_eq!(v["effect"]["navigated_to"], "p2");
-        let round: Step = serde_json::from_value(v).unwrap();
-        assert_eq!(round, step);
-    }
-
-    #[test]
-    fn trace_record_only_round_trips() {
+    fn trace_v3_round_trips() {
        let trace = sample_trace();
        let v = serde_json::to_value(&trace).unwrap();
-        assert!(v.get("version").is_none());
-        assert_eq!(
-            v.get("purpose").and_then(|v| v.as_str()),
-            Some("发布一篇文章")
-        );
-        assert!(v.get("parameters").is_none());
-        assert!(v.get("site").is_none());
-        assert!(v.get("goal").is_none());
-        assert_eq!(
-            v.get("entry")
-                .and_then(|e| e.get("start_url"))
-                .and_then(|u| u.as_str()),
-            Some("https://x.com/editor")
-        );
+        assert_eq!(v.get("version").and_then(|v| v.as_u64()), Some(3));
+        assert!(v.get("pages").is_none());
+        assert_eq!(v["recorder"]["vom"], 1);
+        assert_eq!(v["states"].as_array().unwrap().len(), 2);
        let round: Trace = serde_json::from_value(v).unwrap();
        assert_eq!(round, trace);
    }

    #[test]
-    fn discriminated_union_click_ignores_extra_key_field() {
-        let bad = json!({
-            "op": "click",
-            "id": 1,
-            "page": "p1",
-            "target": { "tag": "button", "name": "OK" },
-            "key": "Enter"
-        });
-        let step: Step = serde_json::from_value(bad).unwrap();
-        assert!(matches!(step, Step::Click { .. }));
+    fn default_fields_are_omitted() {
+        let step = Step::Click {
+            common: sample_common(1, "s1", "s1"),
+            target: TargetDescriptor {
+                element_ref: Some("e1".into()),
+                role: Some("button".into()),
+                name: Some("OK".into()),
+                ctx: None,
+                unmatched: false,
+            },
+        };
        let v = serde_json::to_value(&step).unwrap();
-        assert!(v.get("key").is_none());
+        assert!(v.get("unmatched").is_none());
+        assert!(v["target"].get("ctx").is_none());
+        assert!(v["target"].get("unmatched").is_none());
+    }
+
+    #[test]
+    fn unmatched_target_serializes_flag() {
+        let step = Step::Click {
+            common: sample_common(1, "s1", "s2"),
+            target: TargetDescriptor {
+                element_ref: None,
+                role: Some("button".into()),
+                name: Some("发布".into()),
+                ctx: None,
+                unmatched: true,
+            },
+        };
+        let v = serde_json::to_value(&step).unwrap();
+        assert_eq!(v["target"]["unmatched"], true);
+        assert!(v["target"].get("ref").is_none());
+    }
+
+    #[test]
+    fn recorded_trace_classifies_v2_and_v3() {
+        let v2 = json!({
+            "recorded_at": "2026-07-21T08:00:00Z",
+            "entry": { "start_url": "https://example.com/" },
+            "pages": [{ "id": "p1", "url": "https://example.com/" }],
+            "steps": []
+        });
+        match RecordedTrace::classify_value(&v2).unwrap() {
+            RecordedTrace::V2(_) => {}
+            other => panic!("expected v2, got {other:?}"),
+        }
+
+        let v3 = json!({
+            "version": 3,
+            "recorded_at": "2026-07-21T08:00:00Z",
+            "stopped_by": "user_finish",
+            "entry": { "start_url": "https://example.com/" },
+            "recorder": { "bsk": "0.1.10", "vom": 1 },
+            "states": [],
+            "steps": []
+        });
+        match RecordedTrace::classify_value(&v3).unwrap() {
+            RecordedTrace::V3(t) => assert_eq!(t.version, 3),
+            other => panic!("expected v3, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn recorded_trace_schema_includes_v2_and_v3() {
+        let schema = serde_json::to_value(schemars::schema_for!(RecordStopResult)).unwrap();
+        let variants = schema["definitions"]["RecordedTrace"]["oneOf"]
+            .as_array()
+            .expect("RecordedTrace schema should use oneOf");
+
+        assert_eq!(variants.len(), 2);
    }

    #[test]
    fn extension_trace_deserializes() {
        let v = json!({
+            "version": 3,
            "recorded_at": "2026-07-21T08:00:00Z",
            "started_at": "2026-07-21T07:59:00Z",
            "purpose": "demo",
+            "stopped_by": "user_finish",
            "entry": { "start_url": "https://example.com/editor" },
-            "pages": [
-                { "id": "p1", "url": "https://example.com/editor" },
-                { "id": "p2", "url": "https://example.com/p/99" }
+            "recorder": { "bsk": "0.1.10", "vom": 1 },
+            "states": [
+                { "id": "s1", "url": "https://example.com/editor", "page": "s1.vom.txt" },
+                { "id": "s2", "url": "https://example.com/p/99", "page": "s2.vom.txt" }
            ],
            "steps": [
                {
                    "op": "fill",
                    "id": 1,
-                    "page": "p1",
-                    "target": { "tag": "input", "role": "textbox", "name": "标题" },
-                    "value": "hello"
+                    "state": "s1",
+                    "result": { "state": "s1" },
+                    "target": { "ref": "e1", "role": "textbox", "name": "标题" },
+                    "value": "hello",
+                    "commit": "blur"
                },
                {
                    "op": "click",
                    "id": 2,
-                    "page": "p1",
-                    "target": { "tag": "button", "role": "button", "name": "发布" },
-                    "effect": { "navigated_to": "p2" }
+                    "state": "s1",
+                    "result": { "state": "s2" },
+                    "target": { "ref": "e2", "role": "button", "name": "发布" }
                }
            ]
        });
        let trace: Trace = serde_json::from_value(v).unwrap();
-        assert_eq!(trace.entry.start_url, "https://example.com/editor");
-        assert_eq!(trace.pages.len(), 2);
+        assert_eq!(trace.version, 3);
+        assert_eq!(trace.states.len(), 2);
        assert_eq!(trace.steps.len(), 2);
    }
 }
@@ -0,0 +1,215 @@
+//! Trace v2 — record-only user-action log with `pages[]` and step `page` refs.
+//!
+//! Legacy wire format: no top-level `version` field. New peers omit
+//! `trace_version` on `record_start` to request this shape.
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use super::interaction::KeyModifier;
+use super::record::TraceEntry;
+
+/// Stable semantic handle for an interacted element (v2).
+///
+/// `name` and `nearby_label` are **untrusted page text**.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TargetDescriptorV2 {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub role: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name: Option<String>,
+    pub tag: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub name_attr: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub placeholder: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub nearby_label: Option<String>,
+}
+
+/// Page context dictionary entry — referenced by steps via `page` id.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct PageRef {
+    pub id: String,
+    pub url: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub title: Option<String>,
+}
+
+/// One selected option (`select` op).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct SelectedOptionV2 {
+    pub value: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub label: Option<String>,
+}
+
+/// Observed navigation after a step (objective fact only).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct StepEffectV2 {
+    /// Reference into `pages[]` for the destination page.
+    pub navigated_to: String,
+}
+
+/// Fields shared by every v2 step variant (flattened in JSON).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct StepCommonV2 {
+    pub id: u32,
+    /// Reference into `pages[]`.
+    pub page: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub effect: Option<StepEffectV2>,
+}
+
+/// One recorded user action — discriminated union by `op` (v2).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+#[serde(tag = "op", rename_all = "snake_case")]
+pub enum StepV2 {
+    Navigate {
+        #[serde(flatten)]
+        common: StepCommonV2,
+        to: String,
+    },
+    Click {
+        #[serde(flatten)]
+        common: StepCommonV2,
+        target: TargetDescriptorV2,
+    },
+    Fill {
+        #[serde(flatten)]
+        common: StepCommonV2,
+        target: TargetDescriptorV2,
+        value: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        redacted: Option<bool>,
+    },
+    Select {
+        #[serde(flatten)]
+        common: StepCommonV2,
+        target: TargetDescriptorV2,
+        selection: Vec<SelectedOptionV2>,
+    },
+    Press {
+        #[serde(flatten)]
+        common: StepCommonV2,
+        key: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        modifiers: Option<Vec<KeyModifier>>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        target: Option<TargetDescriptorV2>,
+    },
+}
+
+/// Persisted user-action trace exported by legacy `tool.record_stop` / `await`.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct TraceV2 {
+    /// RFC 3339 timestamp when recording stopped.
+    pub recorded_at: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub started_at: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub purpose: Option<String>,
+    pub entry: TraceEntry,
+    pub pages: Vec<PageRef>,
+    pub steps: Vec<StepV2>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn sample_common(id: u32) -> StepCommonV2 {
+        StepCommonV2 {
+            id,
+            page: "p1".into(),
+            effect: None,
+        }
+    }
+
+    fn sample_target() -> TargetDescriptorV2 {
+        TargetDescriptorV2 {
+            role: Some("button".into()),
+            name: Some("发布".into()),
+            tag: "button".into(),
+            name_attr: None,
+            placeholder: None,
+            nearby_label: None,
+        }
+    }
+
+    #[test]
+    fn trace_v2_has_no_version_field() {
+        let trace = TraceV2 {
+            recorded_at: "2026-07-17T09:01:10Z".into(),
+            started_at: None,
+            purpose: None,
+            entry: TraceEntry {
+                start_url: "https://example.com/".into(),
+            },
+            pages: vec![PageRef {
+                id: "p1".into(),
+                url: "https://example.com/".into(),
+                title: None,
+            }],
+            steps: vec![StepV2::Click {
+                common: sample_common(1),
+                target: sample_target(),
+            }],
+        };
+        let v = serde_json::to_value(&trace).unwrap();
+        assert!(v.get("version").is_none());
+        assert!(v.get("pages").is_some());
+        assert!(v.get("states").is_none());
+    }
+
+    #[test]
+    fn extension_v2_trace_deserializes() {
+        let v = json!({
+            "recorded_at": "2026-07-21T08:00:00Z",
+            "started_at": "2026-07-21T07:59:00Z",
+            "purpose": "demo",
+            "entry": { "start_url": "https://example.com/editor" },
+            "pages": [
+                { "id": "p1", "url": "https://example.com/editor" },
+                { "id": "p2", "url": "https://example.com/p/99" }
+            ],
+            "steps": [
+                {
+                    "op": "fill",
+                    "id": 1,
+                    "page": "p1",
+                    "target": { "tag": "input", "role": "textbox", "name": "标题" },
+                    "value": "hello"
+                },
+                {
+                    "op": "click",
+                    "id": 2,
+                    "page": "p1",
+                    "target": { "tag": "button", "role": "button", "name": "发布" },
+                    "effect": { "navigated_to": "p2" }
+                }
+            ]
+        });
+        let trace: TraceV2 = serde_json::from_value(v).unwrap();
+        assert_eq!(trace.pages.len(), 2);
+        assert_eq!(trace.steps.len(), 2);
+    }
+
+    #[test]
+    fn historical_v2_rejects_hover_steps() {
+        let value = json!({
+            "recorded_at": "2026-07-21T08:00:00Z",
+            "entry": { "start_url": "https://example.com/" },
+            "pages": [{ "id": "p1", "url": "https://example.com/" }],
+            "steps": [{
+                "op": "hover",
+                "id": 1,
+                "page": "p1",
+                "target": { "tag": "button", "name": "结束" }
+            }]
+        });
+
+        assert!(serde_json::from_value::<TraceV2>(value).is_err());
+    }
+}