[NianJiuZst]

Closes #388 when the agreed implementation is merged. This updates the existing RFC implementation; architecture and rollout remain maintainer decisions.

Problem and resulting behavior

Protocol changes currently require editing Rust payloads, TypeScript mirrors, schema exports, dispatch registrations and policy lists separately. Independently updated CLI, daemon and browser-extension installations can also accept a connection while lacking a requested feature.

This PR makes Rust the source for shared contracts and versioned feature requirements. Generated types and validators keep source definitions aligned. Runtime preflight checks reject unsupported optional features before dispatch and identify the component to update, while omitted options retain their existing behavior.

Implementation

• A single Rust method catalog declares wire names, owners, effects, parameter/result types and explicit feature lists. Typed extension handlers, extension policies and daemon scheduling policies must cover their method sets.

• scripts/protocol.mjs generates 45 extension methods, 222 contract definitions and 116 standalone schemas. protocol:check detects missing, changed or unexpected generated files without modifying source files.

• Schemars exports input and output contracts separately. Generated immutable normalizers accept legacy nulls for optional typed fields while preserving arbitrary JSON/dictionary nulls. Ajv standalone validators run in MV3 without a runtime schema compiler.

• Envelope/parameter validation runs before handlers. Invalid results report protocol_error with effect_state: "unknown"; they do not imply safe retry. Failed session-start result validation cleans up the allocated session.

• bsk-protocol/src/compatibility.rs centralizes the existing feature requirements:

  Explicit feature	Daemon protocol	Extension protocol
  Incognito session	1.4	1.4
  Custom borrow confirmation timeout	1.2	1.2
  Request-help policy	1.3	1.0

  Older extensions already implement request-help; their responses remain authoritative. The 1.3 daemon requirement prevents its legacy environment override from disabling that path.

• The CLI probes the daemon over the same IPC connection used for the action. The daemon checks the actual target extension connection before registering/sending the request. Cancellation during preflight drops the probe without dispatching the action.

• unsupported_feature errors include the feature, component, required/actual protocol, effect_state: "none" and actionable recovery. Updating bsk/restarting its daemon is distinguished from updating the affected browser profile. A store update can remain pending while other supported features are used.

• bsk status --json preserves existing top-level fields and adds per-daemon/per-browser compatibility information. The daemon's status wire payload is unchanged. bsk doctor reports limitations and reminds the agent to reload updated Skill instructions. Popup guidance consumes generated requirements too.

• Integrated main b63f551209caba4d7debfc12215b2b7c118bad49, including cooperation, guarded browser mutations and download completion signals. The existing cooperation cleanup test now waits for its response rather than a fixed number of microtasks. An existing updater-test lint was fixed by consuming its byte buffers instead of cloning them.

See version compatibility and protocol ownership.

Validation — 2026-10-23

macOS ARM64; Rust 1.94.1, Node 26.10.0, pnpm 10.17.0; Chrome for Testing 153.0.8010.12.

Check	Result
Rust workspace tests, serial	880 passed, 1 ignored
Rust formatting and all-target Clippy with warnings denied	Passed
Extension suite	2,934 passed, 254 skipped
DSH plugin	560 passed
VOM / localization	82 / 64 passed
Node script tests, including LF/CRLF Skill budgets	13 passed
TypeScript, Biome, Stylelint, extension and DSH production builds	Passed
Cargo Skill and packaged npm Skill verification	Passed
Protocol generation check	45 methods, 222 definitions, 116 schemas; no stale artifacts

Out-of-tree process checks cover daemon protocols 1.0–1.4, unsupported major/invalid versions, same-connection preflight, cancellation during the probe, old/new target profiles, omitted-option behavior, and availability after reconnection. Unsupported features produce no corresponding outgoing action frame.

Released CLI 0.2.1/0.3.3 binaries and extension 0.2.1/0.3.3 ZIPs were downloaded from GitHub Releases and verified against published SHA-256 digests. Browser runs used private daemon homes and owned Chrome profiles. Unpacked extension copies changed only the localhost WebSocket endpoint for isolation.

Real Chrome combination	Verified behavior
Current CLI + daemon + extension	Session lifecycle, navigation, sync/context-bound click, snapshot, element wait, extraction and video start/stop/discard
Current CLI/daemon + released extension 0.3.3	Lifecycle, navigation, snapshot and click
Current CLI/daemon + released extension 0.2.1	Same basic operations; incognito rejected before another page/window was created
Current CLI + released daemon 0.3.3 + current extension	Lifecycle, initial navigation and snapshot
Current CLI + released daemon 0.2.1 + current extension	Same reads; incognito rejected with daemon-specific guidance
Released CLI 0.2.1 + current daemon/extension	Lifecycle, initial navigation and snapshot

The current full-stack run also rejected action recording during active video; the video still finalized with nonzero bytes.

No new test scripts, fixtures, screenshots or logs are committed. The browser-gated skips, Windows behavior and hosted CI are not counted as local passes. Hosted checks are tracked separately on the pushed head.

Compatibility boundaries

• Protocol 1.4, minimum 1.0, and handshake shapes remain unchanged. The initial feature table covers the three versioned features above; it does not reconstruct introduction versions for every historical method or certify every released combination.
• Base connectivity is not full workflow compatibility. Main's existing cooperation policy requires a fresh observation context before page mutations. With a current extension, legacy mutation calls return cooperation_sync_required; the old CLI must be updated for cooperate sync, and that workflow needs a daemon that understands it. The mixed-version browser runs verified this rejection rather than counting it as a successful click.
• tool.cooperate parameters are generated; its existing arbitrary-JSON result remains unconstrained until a shared result type is defined.
• Browser permissions, settings, ownership, readiness and actual side effects remain handler responsibilities. A feature marked available is a protocol-version check.
• A CLI/Skill update cannot replace instructions already retained in an agent conversation or force an extension-store rollout. Recovery remains explicit; requested options are never silently dropped.
• Evaluation retains the existing bounded timeout/cancellation lifecycle. A deadline or cancellation acknowledgement does not prove that arbitrary page JavaScript stopped, and generated contracts do not establish execution safety after timeout.