fix(protocol): align Trace v2/v3 classification and hover steps

Require Trace v3 version const 3, reject mixed pages/states payloads, and
align TypeScript selection optionality with the generated schema. Trace v2
on main already records hover steps, so the frozen v2 schema must accept
them instead of dropping them during reduction.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: shnpd

apps/extension/src/lib/__tests__/trace-reducer.test.ts

@@ -130,7 +130,7 @@ describe("reduceTraceSteps", () => {
     });
   });
 
-  it("drops hover steps unsupported by historical v2 clients", () => {
+  it("keeps hover steps before menu clicks", () => {
     const { steps } = reduceTraceSteps(
       [
         {
@@ -146,11 +146,11 @@ describe("reduceTraceSteps", () => {
       ],
       "https://example.com/app",
     );
-    expect(steps.map((s) => s.op)).toEqual(["click"]);
+    expect(steps.map((s) => s.op)).toEqual(["hover", "click"]);
     expect(steps[0]).toMatchObject({
-      op: "click",
+      op: "hover",
       page: "p1",
-      target: { name: "Profile" },
+      target: { name: "Account" },
     });
   });
 

apps/extension/src/lib/trace-reducer.ts

@@ -18,7 +18,6 @@ export function shouldRecordPress(
 }
 
 function shouldIncludeDraft(step: DraftTraceStep): boolean {
-  if (step.op === "hover") return false;
   if (step.op === "fill" && !(step.value ?? "").trim() && !step.redacted) return false;
   if (step.op === "press" && !shouldRecordPress(step.key, step.modifiers)) return false;
   return true;
@@ -141,7 +140,12 @@ function toV2Step(
         effectForNavigation(step.navigated_to, urlToId),
       );
     case "hover":
-      return null;
+      return {
+        op: "hover",
+        id,
+        page,
+        target: step.target,
+      };
     case "fill":
       return {
         op: "fill",

apps/extension/src/transport/types.ts

@@ -793,6 +793,7 @@ export type DraftTraceStep =
 export type Step =
   | ({ op: "navigate" } & StepCommon & { to: string })
   | ({ op: "click" } & StepCommon & { target: TargetDescriptor })
+  | ({ op: "hover" } & StepCommon & { target: TargetDescriptor })
   | ({ op: "fill" } & StepCommon & {
         target: TargetDescriptor;
         value: string;
@@ -834,7 +835,7 @@ export type StepV3 =
       })
   | ({ op: "select" } & StepCommonV3 & {
         target: TargetDescriptorV3;
-        selection: SelectedOption[];
+        selection?: SelectedOption[];
       })
   | ({ op: "press" } & StepCommonV3 & {
         key: string;
@@ -844,7 +845,7 @@ export type StepV3 =
   | ({ op: "scroll" } & StepCommonV3);
 
 export interface TraceV3 {
-  version: number;
+  version: 3;
   recorded_at: string;
   started_at?: string;
   purpose?: string;

crates/bsk-protocol/schema/tool_record_await_result.json

@@ -512,6 +512,46 @@
             }
           }
         },
+        {
+          "description": "Fields shared by every v2 step variant (flattened in JSON).",
+          "type": "object",
+          "required": [
+            "id",
+            "op",
+            "page",
+            "target"
+          ],
+          "properties": {
+            "effect": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/StepEffectV2"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "id": {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "op": {
+              "type": "string",
+              "enum": [
+                "hover"
+              ]
+            },
+            "page": {
+              "description": "Reference into `pages[]`.",
+              "type": "string"
+            },
+            "target": {
+              "$ref": "#/definitions/TargetDescriptorV2"
+            }
+          }
+        },
         {
           "description": "Fields shared by every v2 step variant (flattened in JSON).",
           "type": "object",
@@ -803,10 +843,10 @@
         },
         "version": {
           "type": "integer",
-          "format": "uint32",
-          "minimum": 0.0
+          "const": 3
         }
-      }
+      },
+      "additionalProperties": false
     },
     "TraceEntry": {
       "description": "Recording entry point — first URL the flow starts from.",
@@ -900,7 +940,8 @@
             "$ref": "#/definitions/StepV2"
           }
         }
-      }
+      },
+      "additionalProperties": false
     }
   }
 }

crates/bsk-protocol/schema/tool_record_stop_result.json

@@ -512,6 +512,46 @@
             }
           }
         },
+        {
+          "description": "Fields shared by every v2 step variant (flattened in JSON).",
+          "type": "object",
+          "required": [
+            "id",
+            "op",
+            "page",
+            "target"
+          ],
+          "properties": {
+            "effect": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/StepEffectV2"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "id": {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "op": {
+              "type": "string",
+              "enum": [
+                "hover"
+              ]
+            },
+            "page": {
+              "description": "Reference into `pages[]`.",
+              "type": "string"
+            },
+            "target": {
+              "$ref": "#/definitions/TargetDescriptorV2"
+            }
+          }
+        },
         {
           "description": "Fields shared by every v2 step variant (flattened in JSON).",
           "type": "object",
@@ -803,10 +843,10 @@
         },
         "version": {
           "type": "integer",
-          "format": "uint32",
-          "minimum": 0.0
+          "const": 3
         }
-      }
+      },
+      "additionalProperties": false
     },
     "TraceEntry": {
       "description": "Recording entry point — first URL the flow starts from.",
@@ -900,7 +940,8 @@
             "$ref": "#/definitions/StepV2"
           }
         }
-      }
+      },
+      "additionalProperties": false
     }
   }
 }

crates/bsk-protocol/schema/trace.json

@@ -51,10 +51,10 @@
     },
     "version": {
       "type": "integer",
-      "format": "uint32",
-      "minimum": 0.0
+      "const": 3
     }
   },
+  "additionalProperties": false,
   "definitions": {
     "FillCommit": {
       "type": "string",

crates/bsk-protocol/schema/trace_v2.json

@@ -42,6 +42,7 @@
       }
     }
   },
+  "additionalProperties": false,
   "definitions": {
     "KeyModifier": {
       "description": "Keyboard modifier flags. Multiple flags may be combined; the extension folds them into CDP's bitfield (`alt=1, ctrl=2, meta=4, shift=8`).",
@@ -189,6 +190,46 @@
             }
           }
         },
+        {
+          "description": "Fields shared by every v2 step variant (flattened in JSON).",
+          "type": "object",
+          "required": [
+            "id",
+            "op",
+            "page",
+            "target"
+          ],
+          "properties": {
+            "effect": {
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/StepEffectV2"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "id": {
+              "type": "integer",
+              "format": "uint32",
+              "minimum": 0.0
+            },
+            "op": {
+              "type": "string",
+              "enum": [
+                "hover"
+              ]
+            },
+            "page": {
+              "description": "Reference into `pages[]`.",
+              "type": "string"
+            },
+            "target": {
+              "$ref": "#/definitions/TargetDescriptorV2"
+            }
+          }
+        },
         {
           "description": "Fields shared by every v2 step variant (flattened in JSON).",
           "type": "object",