feat(protocol): add Trace v3 with v2-compatible negotiation

[shnpd]

Summary

在 #100 提供的录制安全 VOM 观察能力之上，引入 Trace v3 协议模型、版本协商和 v2/v3 兼容层。

本 PR 只定义并验证协议边界，不启用 Trace v3 录制流程。省略 trace_version 时仍使用 Trace v2，后续 PR 将实现 v3 状态捕获、trace reduction 和目录 bundle 导出。

Refs #90

Changes

Trace v3 protocol

新增状态—动作—状态形式的 Trace v3：

• 顶层 version: 3
• states[] 页面观察字典
• 步骤通过 state 和 result.state 关联动作前后状态
• recorder 记录 bsk 与 VOM 格式版本
• stopped_by 区分用户完成和 CLI 停止
• 新增 NavigationCause、FillCommit 和 scroll step
• v3 target 支持 ref、role、name、ctx 和 unmatched
• 支持 wire-only observation body 与 disk-only page filename

Rust 和 TypeScript 定义保持一致，包括：

• TraceV3
• StepV3
• TargetDescriptorV3
• TraceState
• RecorderInfo
• StopReason
• NavigationCause
• FillCommit

Trace v2 compatibility

将现有 Trace v2 格式保留为独立协议模型：

• 新增 record_v2.rs
• 保留无顶层 version 的 pages[] 格式
• 保留现有 navigate、click、hover、fill、select 和 press steps
• 保留原有 target、navigation effect 和 selected option 字段
• 新增 TraceV2、StepV2 和相关 TypeScript aliases

hover 是现有 v2 协议的一部分，本 PR 明确保留其 Rust、TypeScript 和 JSON Schema 支持。

Version negotiation

协议版本从 1.0 提升到 1.1，兼容下限保持为 1.0：

• 1.1 daemon 与 extension 正常连接
• 1.0 对端仍可连接，并标记为 version skew
• 1.2 对端在兼容 floor 满足时仍可连接
• major version 不匹配或 compatibility floor 不满足时拒绝连接
• daemon status 使用统一的 PROTOCOL_VERSION

这允许新旧 CLI、daemon 和 extension 在 Trace v3 分阶段发布期间继续协作。

Trace format negotiation

RecordStartParams 新增：

• trace_version
• max_page_tokens
• redact_values

行为约定：

• 省略 trace_version：请求 Trace v2
• trace_version: 3：请求 Trace v3
• 本 PR 中 CLI 仍省略该字段，因此默认录制行为没有变化

RecordStopResult 和 RecordAwaitResult 通过 RecordedTrace 支持返回 v2 或 v3。

Validation

强化协议载荷校验：

• Trace v3 的 version 必须严格等于 3
• 带 version: 3 的载荷不能包含 legacy pages[]
• 无 version 的 Trace v2 不能包含 states[]
• 不支持的 version 会被拒绝
• 模糊或混合的 v2/v3 载荷不会被静默分类
• Rust runtime classification 与生成的 oneOf schema 保持一致

Generated schemas

新增或更新：

• trace_v2.json
• trace.json
• trace_step.json
• tool_record_start_params.json
• tool_record_stop_result.json
• tool_record_await_result.json

dump-schema 现在也会生成独立的 Trace v2 schema。

CLI compatibility

CLI 可以反序列化并保存 RecordedTrace::V2 或 RecordedTrace::V3，同时分别计算 step 数量。

本 PR 不切换到 Trace v3 bundle 输出；目录结构导出由后续 PR 实现。

Compatibility matrix

• New CLI + new extension: defaults to Trace v2
• New CLI + protocol 1.0 extension: remains compatible
• Protocol 1.0 CLI + new extension: receives Trace v2
• Explicit trace_version: 3: reserved for the upcoming v3 recorder implementation
• Existing Trace v2 files remain readable
• Existing v2 hover steps remain valid

Verification

• Generated schemas match committed schema files
• Extension tests: 52 files, 649 tests passed
• Extension TypeScript compilation passed
• Biome and Stylelint passed
• Rust formatting and Clippy passed
• GitHub Rust fmt, Clippy and tests passed
• GitHub frontend lint, typecheck, tests and build passed
• GitHub Node script tests passed
• GitHub source scan passed

Review focus

Please focus review on:

1. Rust/TypeScript/schema parity for Trace v2 and Trace v3
2. RecordedTrace classification boundaries
3. Preservation of Trace v2 behavior, especially hover steps
4. Protocol 1.0/1.1 compatibility negotiation
5. Whether the PR remains limited to protocol definition and compatibility

[Copilot]

Pull request overview

This PR introduces a new Trace v3 protocol model (state → action → state) alongside an explicit Trace v2 compatibility model, and updates protocol/version negotiation so new/old CLI, daemon, and extension can interoperate during a phased rollout.

Changes:

• Add Trace v3 types (states, step result linking, recorder metadata, stop reason, navigation cause/fill commit/scroll) plus RecordedTrace (v2|v3) classification and schemas.
• Preserve Trace v2 as an isolated model (record_v2.rs) with its own schema output, including legacy hover support.
• Bump protocol version to 1.1 and update handshake/status/test expectations; update CLI to handle RecordedTrace.

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
crates/bsk-protocol/src/tools/record.rs	Defines Trace v3 model, negotiation params, and RecordedTrace (v2/v3) classification.
crates/bsk-protocol/src/tools/record_v2.rs	Adds isolated Trace v2 wire model (legacy pages[], page refs, v2 steps incl. hover).
crates/bsk-protocol/src/tools/mod.rs	Exposes the new record_v2 module.
crates/bsk-protocol/src/bin/dump-schema.rs	Extends schema dumper to emit standalone trace_v2 schema.
crates/bsk-protocol/schema/trace.json	Updates committed Trace schema to v3 (version=3, states, recorder, stopped_by).
crates/bsk-protocol/schema/trace_v2.json	Adds committed standalone Trace v2 schema.
crates/bsk-protocol/schema/trace_step.json	Updates step schema for v3 fields (state/result/cause/commit/scroll).
crates/bsk-protocol/schema/tool_record_stop_result.json	Updates stop result schema to return RecordedTrace (v2 or v3).
crates/bsk-protocol/schema/tool_record_start_params.json	Adds record start negotiation fields (trace_version, token/redaction knobs).
crates/bsk-protocol/schema/tool_record_await_result.json	Updates await result schema to return RecordedTrace (v2 or v3).
crates/bsk-cli/tests/ws_handshake.rs	Updates test handshake params/expectations for protocol 1.1.
crates/bsk-cli/tests/tools_m9_ipc.rs	Updates IPC handshake test params for protocol 1.1.
crates/bsk-cli/tests/tools_m8_ipc.rs	Updates IPC handshake test params for protocol 1.1.
crates/bsk-cli/tests/tools_m7_ipc.rs	Updates IPC handshake test params for protocol 1.1.
crates/bsk-cli/tests/tools_ipc.rs	Updates IPC handshake test params for protocol 1.1.
crates/bsk-cli/tests/status_cmd.rs	Updates bsk status JSON protocol_version expectation to 1.1.
crates/bsk-cli/tests/sessions_ipc.rs	Updates session IPC handshake test params for protocol 1.1.
crates/bsk-cli/tests/session_user_interrupt.rs	Updates handshake params for protocol 1.1 in interrupt test.
crates/bsk-cli/tests/per_session_queue.rs	Updates handshake params for protocol 1.1 in queue test.
crates/bsk-cli/tests/handshake_compat.rs	Updates/extends protocol compatibility matrix tests (skew/reject scenarios).
crates/bsk-cli/tests/cancel_forwarding.rs	Updates handshake params for protocol 1.1 in cancel forwarding test.
crates/bsk-cli/tests/browser_wait.rs	Updates handshake params for protocol 1.1 in browser wait test.
crates/bsk-cli/src/daemon/state.rs	Bumps daemon PROTOCOL_VERSION constant to 1.1.
crates/bsk-cli/src/daemon/start.rs	Uses unified PROTOCOL_VERSION in daemon status reporting.
crates/bsk-cli/src/cli/record.rs	Updates CLI to write/render RecordedTrace and compute step counts for v2/v3.
crates/bsk-cli/src/cli/doctor.rs	Updates doctor tests/fixtures for protocol 1.1 reporting.
apps/extension/src/transport/types.ts	Adds TS v3 protocol types + RecordedTrace union, keeps v2 types/aliases.
apps/extension/src/transport/handshake.ts	Bumps extension PROTOCOL_VERSION to 1.1 (floor remains 1.0).
apps/extension/src/transport/tests/handshake.test.ts	Updates handshake test expectations for protocol 1.1.
apps/extension/src/lib/tests/connection-controller.test.ts	Updates connection-state compat tests for protocol 1.1 scenarios.

Suppressed comments (1)

crates/bsk-protocol/src/tools/record.rs:151

• Step does not use #[serde(deny_unknown_fields)], so v3 steps can silently accept legacy v2-only keys (e.g. page / effect) without failing deserialization. This weakens the “no mixed v2/v3 payloads” validation guarantee and can hide producer bugs.

/// One recorded user action — discriminated union by `op`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "op", rename_all = "snake_case")]
pub enum Step {
    Navigate {

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.