Gate remote endpoints by capabilities

Author: SqlRush

docs/cc-100-roadmap.md

@@ -1488,6 +1488,8 @@ M7 补充：terminal input parser 和 configurable keybinding name parser 现在
 
 本轮补充：remote registration 响应会持久化协议版本、能力列表和 lease renew/refresh endpoint，并在 `/status show remote` 中脱敏展示；注册协议版本现在强制校验，只接受空 legacy 版本、`ccr.remote.v1` 和 `ccr.remote.v2`，未知版本会把 registration 标为 failed 并清掉可用 endpoint。更完整的云端协议演进策略仍未完成。
 
+本轮补充：remote registration 的显式 capabilities/features 会参与 endpoint 启用：非空能力列表缺少 `websocket_protocol` 时忽略 websocket URL，缺少 `lease_renew`/`lease_refresh` 时忽略 renew endpoint，并把 capability warning 写入 registration state 和 `/status show remote`；空能力列表仍按 legacy 兼容处理。更完整的云端能力矩阵仍未完成。
+
 本轮补充：daemon remote delivery 会在投递未过期 leased event 前，对注册级同源 lease renew/refresh endpoint 做 best-effort POST，并对 transport error、408/429/5xx 做一次短退避重试，把 renew sent/error 计数写入 pump state、structured result 和 `/status show remote`；完整续期策略和云端协议演进策略仍未完成。
 
 本轮补充：remote delivery ack POST 同样会对 transport error、408/429/5xx 做一次短退避重试，保持 delivered/duplicate/failed/expired ack 在瞬时服务端错误下更稳；更完整的远端协议演进策略仍未完成。

docs/claude-code-go-rewrite-plan.md

@@ -747,6 +747,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：remote settings 新增 `registrationUrl`/`authToken`，`advanced.bridge=true` 写出 remote service manifest 后会把 manifest POST 到注册 URL，并将 registered/failed/disabled、HTTP status、远端 session/websocket/poll 信息写入 session-scoped `remote-registration.json`；`/status show remote` 可审计注册状态且不泄露 token/query。完整 CCR 云端长连接仍未完成。
 - 本轮补充：remote registration 响应解析现在会先读取顶层字段，再递归解包 `data`、`session`、`remote_session`、`registration`、`result`、`payload` wrapper，兼容云端把 remote session、registration id、websocket/poll endpoint 放在 envelope 内返回。更深的注册协议协商和租约刷新仍未完成。
 - 本轮补充：remote registration 响应现在会持久化 `protocolVersion`/`protocol_version`、`capabilities`/`features` 和 `leaseRenewUrl`/`lease_refresh_url` 元数据，并在 `/status show remote` 中以脱敏 URL 暴露协议版本、能力列表和 lease renew endpoint；注册协议版本现在强制校验，只接受空 legacy 版本、`ccr.remote.v1` 和 `ccr.remote.v2`，未知版本会把 registration 标为 failed 并清掉可用 endpoint。更完整的云端协议演进策略仍未完成。
+- 本轮补充：remote registration 的显式 `capabilities`/`features` 现在会参与 endpoint 启用：非空能力列表缺少 `websocket_protocol` 时会忽略 websocket URL，缺少 `lease_renew`/`lease_refresh` 时会忽略 lease renew endpoint，并把 capability warning 写入 `remote-registration.json` 与 `/status show remote`；空能力列表仍按 legacy 兼容处理。更完整的云端能力矩阵和协议演进策略仍未完成。
 - 本轮补充：新增 session-scoped `remote-pump.json` 和 daemon remote 消息泵；daemon tick 会在 ScheduleCron due tick 后优先读取 registered `websocket_url`，通过 Bearer auth 建立 WebSocket、读取单帧事件并复用 poll 解码/`RemoteTrigger` 注入路径；无 WebSocket 或 WebSocket 失败且存在 poll URL 时回退到带 cursor 的 poll 拉取。pump 状态会记录 transport、websocket/poll URL 脱敏值、cursor、HTTP status、event/delivered/duplicate/error 计数，`/status show remote` 可审计当前传输。完整 CCR WebSocket 常驻持久 stream 和云端协议 hardening 仍未完成。
 - 本轮补充：remote WebSocket pump 现在支持单次 tick 内读取多帧事件，并在握手/读帧失败或非正常 close 时按可配置 backoff 重连；daemon 默认读取最多 8 帧、最多重连 2 次，并把 frame/connect/reconnect 计数和 WebSocket close code 写入 `remote-pump.json` 和 `/status show remote`。完整 CCR 云端 WebSocket 常驻持久 stream 与更深协议 hardening 仍未完成。
 - 本轮补充：`internal/remote` 新增 callback 型 `StreamWebSocketEvents` primitive，可保持 WebSocket 连接逐帧解码并把事件批次交给调用方，支持 context 取消、可选帧上限、handler 错误传播、异常 close/读错后的 backoff 重连以及 `ReconnectAttempts < 0` 无限重连语义；该能力为 daemon 常驻 stream 托管接线打底。完整云端协议 hardening 仍未完成。

internal/conversation/run.go

@@ -1855,6 +1855,9 @@ func formatRemoteRegistration(state remotepkg.RegistrationState) []string {
 	if state.Error != "" {
 		lines = append(lines, "Remote registration error: "+state.Error)
 	}
+	if len(state.CapabilityWarnings) > 0 {
+		lines = append(lines, "Remote registration warnings: "+strings.Join(state.CapabilityWarnings, "; "))
+	}
 	if state.RegisteredAt != "" {
 		lines = append(lines, "Remote registered at: "+state.RegisteredAt)
 	}

internal/conversation/run_test.go

@@ -2732,6 +2732,21 @@ func TestFormatRemoteRegistrationReportsUnsupportedProtocol(t *testing.T) {
 	}
 }
 
+func TestFormatRemoteRegistrationReportsCapabilityWarnings(t *testing.T) {
+	lines := formatRemoteRegistration(remotepkg.RegistrationState{
+		RuntimeState:       remotepkg.RegistrationRegistered,
+		RemoteSessionID:    "remote-limited",
+		ProtocolVersion:    remotepkg.RemoteProtocolVersionV1,
+		Capabilities:       []string{"remote_trigger"},
+		PollURL:            "https://remote.example/poll?token=secret",
+		CapabilityWarnings: []string{"websocket url ignored: missing websocket_protocol capability", "lease renew url ignored: missing lease_renew capability"},
+	})
+	text := strings.Join(lines, "\n")
+	if !strings.Contains(text, "Remote registration warnings: websocket url ignored: missing websocket_protocol capability; lease renew url ignored: missing lease_renew capability") || strings.Contains(text, "token=secret") {
+		t.Fatalf("registration status = %q", text)
+	}
+}
+
 func TestRunnerExecutesStatusShowSectionsWithoutQuery(t *testing.T) {
 	client := &fakeClient{}
 	t.Setenv("CLAUDE_CONFIG_DIR", t.TempDir())

internal/remote/registration.go

@@ -34,24 +34,25 @@ const (
 var supportedRemoteProtocolVersions = []string{RemoteProtocolVersionV1, RemoteProtocolVersionV2}
 
 type RegistrationState struct {
-	SessionID        contracts.ID `json:"session_id,omitempty"`
-	EnvironmentID    string       `json:"environment_id,omitempty"`
-	RuntimeState     string       `json:"runtime_state"`
-	RegistrationURL  string       `json:"registration_url,omitempty"`
-	ManifestPath     string       `json:"manifest_path,omitempty"`
-	LastAttemptAt    string       `json:"last_attempt_at,omitempty"`
-	RegisteredAt     string       `json:"registered_at,omitempty"`
-	StatusCode       int          `json:"status_code,omitempty"`
-	RemoteSessionID  string       `json:"remote_session_id,omitempty"`
-	RegistrationID   string       `json:"registration_id,omitempty"`
-	ProtocolVersion  string       `json:"protocol_version,omitempty"`
-	Capabilities     []string     `json:"capabilities,omitempty"`
-	WebSocketURL     string       `json:"websocket_url,omitempty"`
-	PollURL          string       `json:"poll_url,omitempty"`
-	LeaseRenewURL    string       `json:"lease_renew_url,omitempty"`
-	Message          string       `json:"message,omitempty"`
-	Error            string       `json:"error,omitempty"`
-	ManifestServices int          `json:"manifest_services,omitempty"`
+	SessionID          contracts.ID `json:"session_id,omitempty"`
+	EnvironmentID      string       `json:"environment_id,omitempty"`
+	RuntimeState       string       `json:"runtime_state"`
+	RegistrationURL    string       `json:"registration_url,omitempty"`
+	ManifestPath       string       `json:"manifest_path,omitempty"`
+	LastAttemptAt      string       `json:"last_attempt_at,omitempty"`
+	RegisteredAt       string       `json:"registered_at,omitempty"`
+	StatusCode         int          `json:"status_code,omitempty"`
+	RemoteSessionID    string       `json:"remote_session_id,omitempty"`
+	RegistrationID     string       `json:"registration_id,omitempty"`
+	ProtocolVersion    string       `json:"protocol_version,omitempty"`
+	Capabilities       []string     `json:"capabilities,omitempty"`
+	CapabilityWarnings []string     `json:"capability_warnings,omitempty"`
+	WebSocketURL       string       `json:"websocket_url,omitempty"`
+	PollURL            string       `json:"poll_url,omitempty"`
+	LeaseRenewURL      string       `json:"lease_renew_url,omitempty"`
+	Message            string       `json:"message,omitempty"`
+	Error              string       `json:"error,omitempty"`
+	ManifestServices   int          `json:"manifest_services,omitempty"`
 }
 
 type RegistrationOptions struct {
@@ -157,6 +158,7 @@ func RegisterManifest(ctx context.Context, options RegistrationOptions) Registra
 		state.PollURL = ""
 		state.LeaseRenewURL = ""
 	}
+	applyRemoteCapabilityGates(&state)
 	return state
 }
 
@@ -327,6 +329,40 @@ func validateRemoteProtocolVersion(version string) error {
 	return fmt.Errorf("unsupported remote protocol version %q; supported: %s", text, strings.Join(supportedRemoteProtocolVersions, ", "))
 }
 
+func applyRemoteCapabilityGates(state *RegistrationState) {
+	if state == nil || len(state.Capabilities) == 0 {
+		return
+	}
+	if strings.TrimSpace(state.WebSocketURL) != "" && !hasRemoteCapability(state.Capabilities, "websocket_protocol", "websocket", "websocket_stream") {
+		state.WebSocketURL = ""
+		state.CapabilityWarnings = append(state.CapabilityWarnings, "websocket url ignored: missing websocket_protocol capability")
+	}
+	if strings.TrimSpace(state.LeaseRenewURL) != "" && !hasRemoteCapability(state.Capabilities, "lease_renew", "lease_refresh") {
+		state.LeaseRenewURL = ""
+		state.CapabilityWarnings = append(state.CapabilityWarnings, "lease renew url ignored: missing lease_renew capability")
+	}
+}
+
+func hasRemoteCapability(capabilities []string, names ...string) bool {
+	if len(capabilities) == 0 {
+		return false
+	}
+	wanted := make(map[string]bool, len(names))
+	for _, name := range names {
+		text := strings.TrimSpace(strings.ToLower(name))
+		if text != "" {
+			wanted[text] = true
+		}
+	}
+	for _, capability := range capabilities {
+		text := strings.TrimSpace(strings.ToLower(capability))
+		if wanted[text] {
+			return true
+		}
+	}
+	return false
+}
+
 func remoteRegistrationError(status string, body []byte) string {
 	bodyText := strings.TrimSpace(string(body))
 	if bodyText == "" {

internal/remote/registration_test.go

@@ -70,7 +70,7 @@ func TestRegisterManifestAcceptsWrappedResponse(t *testing.T) {
 				"registration":{
 					"id":"reg-wrapped",
 					"protocol_version":"ccr.remote.v2",
-					"features":"remote_trigger lease_refresh",
+					"features":"websocket_protocol remote_trigger lease_refresh",
 					"web_socket_url":"wss://remote/wrapped/ws",
 					"eventsUrl":"https://remote/wrapped/events",
 					"lease_refresh_url":"https://remote/wrapped/leases/refresh",
@@ -93,13 +93,45 @@ func TestRegisterManifestAcceptsWrappedResponse(t *testing.T) {
 	if state.RuntimeState != RegistrationRegistered || state.RemoteSessionID != "remote-wrapped" || state.RegistrationID != "reg-wrapped" || state.ProtocolVersion != RemoteProtocolVersionV2 || state.WebSocketURL != "wss://remote/wrapped/ws" || state.PollURL != "https://remote/wrapped/events" || state.LeaseRenewURL != "https://remote/wrapped/leases/refresh" || state.Message != "registered" {
 		t.Fatalf("registration state = %#v", state)
 	}
-	if len(state.Capabilities) != 2 || state.Capabilities[0] != "remote_trigger" || state.Capabilities[1] != "lease_refresh" {
+	if len(state.Capabilities) != 3 || state.Capabilities[0] != "websocket_protocol" || state.Capabilities[1] != "remote_trigger" || state.Capabilities[2] != "lease_refresh" {
 		t.Fatalf("registration state = %#v", state)
 	}
 }
 
-func TestRegisterManifestRejectsUnsupportedProtocolVersion(t *testing.T) {
+func TestRegisterManifestGatesEndpointsByCapabilities(t *testing.T) {
 	now := time.Date(2026, 6, 17, 11, 4, 0, 0, time.UTC)
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("content-type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"remoteSessionId":"remote-limited",
+			"protocolVersion":"ccr.remote.v1",
+			"capabilities":["remote_trigger"],
+			"websocketUrl":"wss://remote/limited/ws",
+			"pollUrl":"https://remote/limited/events",
+			"leaseRenewUrl":"https://remote/limited/leases/renew"
+		}`))
+	}))
+	defer server.Close()
+
+	state := RegisterManifest(context.Background(), RegistrationOptions{
+		RegistrationURL: server.URL + "/register",
+		Manifest: Manifest{
+			SessionID:     "sess_limited",
+			EnvironmentID: "env-prod",
+			Services:      []Service{{Name: "daemon", RuntimeState: "running"}},
+		},
+		Now: now,
+	})
+	if state.RuntimeState != RegistrationRegistered || state.PollURL != "https://remote/limited/events" || state.WebSocketURL != "" || state.LeaseRenewURL != "" {
+		t.Fatalf("registration state = %#v", state)
+	}
+	if len(state.CapabilityWarnings) != 2 || !strings.Contains(state.CapabilityWarnings[0], "websocket url ignored") || !strings.Contains(state.CapabilityWarnings[1], "lease renew url ignored") {
+		t.Fatalf("capability warnings = %#v", state.CapabilityWarnings)
+	}
+}
+
+func TestRegisterManifestRejectsUnsupportedProtocolVersion(t *testing.T) {
+	now := time.Date(2026, 6, 17, 11, 5, 0, 0, time.UTC)
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("content-type", "application/json")
 		_, _ = w.Write([]byte(`{
@@ -131,7 +163,7 @@ func TestRegisterManifestRejectsUnsupportedProtocolVersion(t *testing.T) {
 }
 
 func TestRegisterManifestHandlesDisabledAndFailedState(t *testing.T) {
-	now := time.Date(2026, 6, 17, 11, 5, 0, 0, time.UTC)
+	now := time.Date(2026, 6, 17, 11, 6, 0, 0, time.UTC)
 	manifest := Manifest{SessionID: "sess_remote", EnvironmentID: "env-prod"}
 	disabled := RegisterManifest(context.Background(), RegistrationOptions{Manifest: manifest, Now: now})
 	if disabled.RuntimeState != RegistrationDisabled || disabled.Error != "" || disabled.SessionID != "sess_remote" {