@team-agent/installer 0.5.1 → 0.5.2

package/crates/team-agent/src/cli/tests/named_address.rs

@@ -75,6 +75,38 @@ fn leader_team(session: &str, pane: &str, socket: &str) -> serde_json::Value {
     })
 }
 
+fn app_server_leader_team(
+    ws: &Path,
+    endpoint: &str,
+    thread_id: &str,
+    session_id: &str,
+) -> serde_json::Value {
+    json!({
+        "session_name": "alpha-session",
+        "agents": {},
+        "leader_receiver": {
+            "mode": "codex_app_server",
+            "transport_kind": "codex_app_server",
+            "status": "attached",
+            "provider": "codex",
+            "owner_epoch": 3,
+            "app_server": {
+                "socket": endpoint,
+                "thread_id": thread_id,
+                "session_id": session_id,
+                "cwd": ws.to_string_lossy(),
+                "cli_version": "codex-appserver-team-agent-test/0.139.0",
+                "bound_at": "2026-07-05T00:00:00Z"
+            }
+        },
+        "team_owner": {
+            "provider": "codex",
+            "transport_kind": "codex_app_server",
+            "owner_epoch": 3
+        }
+    })
+}
+
 fn pane(session: &str, window: &str, pane_id: &str) -> PaneInfo {
     PaneInfo {
         pane_id: PaneId::new(pane_id),
@@ -323,6 +355,105 @@ fn resolve_leader_name_after_rebind() {
     let _ = std::fs::remove_dir_all(&ws);
 }
 
+#[test]
+fn resolve_app_server_leader_name_uses_typed_receiver_not_tmux_pane() {
+    let ws = named_ws("appserver-leader-resolve");
+    let fake = crate::app_server_test_support::FakeAppServer::start(
+        "named-resolve",
+        crate::app_server_test_support::FakeAppServerScript::happy(
+            "thread-live",
+            "session-live",
+            ws.to_str().unwrap(),
+        ),
+    );
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": app_server_leader_team(&ws, fake.endpoint(), "thread-live", "session-live")
+        })),
+    );
+
+    let resolved = resolve_name_with_transport(&ws, "alpha/leader", &OfflineTransport::new())
+        .expect("app-server leader name resolves by typed receiver");
+
+    assert_eq!(resolved.target_kind, NamedTargetKind::Leader);
+    assert_eq!(resolved.transport_kind.as_deref(), Some("codex_app_server"));
+    assert!(
+        resolved.pane_id.is_empty(),
+        "app-server leader is not pane-addressed"
+    );
+    assert_eq!(
+        resolved
+            .app_server
+            .as_ref()
+            .and_then(|app| app.get("thread_id"))
+            .and_then(serde_json::Value::as_str),
+        Some("thread-live")
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+#[test]
+fn resolve_app_server_leader_name_fails_closed_on_transport_conflict() {
+    let ws = named_ws("appserver-leader-conflict");
+    let mut team = app_server_leader_team(
+        &ws,
+        "unix:///tmp/team-agent-should-not-connect.sock",
+        "thread-live",
+        "session-live",
+    );
+    team["leader_receiver"]["mode"] = json!("direct_tmux");
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": team
+        })),
+    );
+
+    let err = resolve_name_with_transport(&ws, "alpha/leader", &OfflineTransport::new())
+        .expect_err("conflicting mode/transport_kind must fail closed");
+
+    assert_eq!(err.kind, NamedAddressErrorKind::NameNotLive);
+    assert!(err.log.contains("mode=direct_tmux"), "{err}");
+    assert!(err.log.contains("transport_kind=codex_app_server"), "{err}");
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+#[test]
+fn send_to_name_app_server_leader_submits_turn_without_tmux_pane() {
+    let ws = named_ws("appserver-leader-send");
+    let fake = crate::app_server_test_support::FakeAppServer::start(
+        "named-send",
+        crate::app_server_test_support::FakeAppServerScript::happy(
+            "thread-live",
+            "session-live",
+            ws.to_str().unwrap(),
+        ),
+    );
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": app_server_leader_team(&ws, fake.endpoint(), "thread-live", "session-live")
+        })),
+    );
+    let args = named_send_args(&ws, Some("alpha/leader"), None, None, &["hello appserver"]);
+
+    let result = cmd_send(&args).expect("named app-server send should succeed");
+    let value = match result.output {
+        CmdOutput::Json(value) => value,
+        other => panic!("expected json output, got {other:?}"),
+    };
+
+    assert_eq!(value["ok"], json!(true));
+    assert_eq!(value["transport_kind"], json!("codex_app_server"));
+    assert_eq!(fake.received_turns().len(), 1);
+    assert_eq!(
+        fake.received_turns()[0]["params"]["clientUserMessageId"],
+        value["message_id"]
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
 #[test]
 fn resolve_name_invalid_syntax() {
     let ws = named_ws("invalid");

package/crates/team-agent/src/cli/tests/run_delegation.rs

@@ -206,6 +206,7 @@ fn current_uid() -> Option<String> {
             team_id: None,
             yes: true,
             no_display: false,
+            backend: None,
             json: true,
         };
         let _ = cmd_quick_start(&args); // real quick_start compiles the spec before any coordinator/launch step
@@ -240,6 +241,7 @@ fn current_uid() -> Option<String> {
             team_id: None,
             yes: false,
             no_display: false,
+            backend: None,
             json: true,
         };
         let text = outcome_text(cmd_quick_start(&args));

package/crates/team-agent/src/cli/types.rs

@@ -272,6 +272,13 @@ pub struct QuickStartArgs {
     pub yes: bool,
     pub no_display: bool,
     pub json: bool,
+    /// 0.5.x Phase 1d Batch 2: explicit backend override
+    /// (`--backend <tmux|conpty>`). `None` = default (factory 5-layer
+    /// resolution; almost always `tmux` on a cold quick-start).
+    /// Explicit `Some("conpty")` on a host without a live shim client
+    /// surfaces `MuxUnavailable` honestly (CR C-1 ①) — NEVER silent
+    /// downgrade to tmux. Explicit `Some("pty")` refuses (CR C-1 ②).
+    pub backend: Option<String>,
     // Stage QR (quick-start/restart separation, design doc
     // .team/artifacts/quickstart-restart-separation-design.md): the
     // `fresh` field is intentionally REMOVED. Reset semantics now live
@@ -440,6 +447,16 @@ pub struct AttachLeaderArgs {
     pub json: bool,
 }
 
+/// Explicit Codex app-server leader binding args.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AttachAppServerLeaderArgs {
+    pub workspace: PathBuf,
+    pub team: Option<String>,
+    pub socket: String,
+    pub thread_id: String,
+    pub json: bool,
+}
+
 /// `identity`(`parser.py:256`)。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct IdentityArgs {

package/crates/team-agent/src/codex_app_server.rs

@@ -0,0 +1,488 @@
+//! Minimal Codex app-server Unix-socket WebSocket client for leader delivery.
+
+use serde_json::{json, Value};
+use std::io::{Read, Write};
+use std::os::unix::fs::{FileTypeExt, MetadataExt, PermissionsExt};
+use std::os::unix::net::UnixStream;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+pub const APP_SERVER_PROTOCOL_FIXTURE_CLI_MIN: &str = "0.139.0";
+pub const APP_SERVER_PROTOCOL_FIXTURE_CLI_MAX: &str = "0.139.x";
+pub const APP_SERVER_PROTOCOL_REQUIRES_USER_AGENT: bool = true;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppServerBinding {
+    pub socket: String,
+    pub thread_id: String,
+    pub session_id: String,
+    pub cwd: String,
+    pub cli_version: String,
+    pub bound_at: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AppServerSubmit {
+    pub turn_id: String,
+    pub turn_status: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum AppServerError {
+    SocketUnreachable(String),
+    SocketOwnershipInvalid(String),
+    ThreadNotLive(String),
+    ThreadStale { expected: Value, actual: Value },
+    LeaderBusy(String),
+    ApprovalUnsupported(String),
+    ProtocolMismatch(String),
+    MissingUserAgent,
+    Io(String),
+    Json(String),
+}
+
+impl AppServerError {
+    pub fn code(&self) -> &'static str {
+        match self {
+            Self::SocketUnreachable(_) => "socket_unreachable",
+            Self::SocketOwnershipInvalid(_) => "socket_ownership_invalid",
+            Self::ThreadNotLive(_) => "thread_not_live",
+            Self::ThreadStale { .. } => "app_server_thread_stale",
+            Self::LeaderBusy(_) => "leader_busy",
+            Self::ApprovalUnsupported(_) => "approval_unsupported",
+            Self::ProtocolMismatch(_) => "protocol_mismatch",
+            Self::MissingUserAgent => "protocol_mismatch_missing_user_agent",
+            Self::Io(_) => "io_error",
+            Self::Json(_) => "json_error",
+        }
+    }
+}
+
+impl std::fmt::Display for AppServerError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::SocketUnreachable(msg)
+            | Self::SocketOwnershipInvalid(msg)
+            | Self::ThreadNotLive(msg)
+            | Self::LeaderBusy(msg)
+            | Self::ApprovalUnsupported(msg)
+            | Self::ProtocolMismatch(msg)
+            | Self::Io(msg)
+            | Self::Json(msg) => write!(f, "{}:{msg}", self.code()),
+            Self::ThreadStale { expected, actual } => {
+                write!(f, "{}:expected={expected},actual={actual}", self.code())
+            }
+            Self::MissingUserAgent => f.write_str(self.code()),
+        }
+    }
+}
+
+impl std::error::Error for AppServerError {}
+
+pub fn attach_probe(endpoint: &str, thread_id: &str) -> Result<AppServerBinding, AppServerError> {
+    check_socket_ownership(endpoint)?;
+    let socket = socket_path(endpoint)?;
+    let mut client = AppServerClient::connect(&socket)?;
+    let user_agent = client.initialize()?;
+    let resume = client.resume(thread_id)?;
+    Ok(AppServerBinding {
+        socket: endpoint.to_string(),
+        thread_id: resume.thread_id,
+        session_id: resume.session_id,
+        cwd: resume.cwd,
+        cli_version: user_agent,
+        bound_at: chrono::Utc::now().to_rfc3339(),
+    })
+}
+
+pub fn submit_to_bound_thread(
+    binding: &AppServerBinding,
+    message_id: &str,
+    rendered: &str,
+) -> Result<AppServerSubmit, AppServerError> {
+    let socket = socket_path(&binding.socket)?;
+    let mut client = AppServerClient::connect(&socket)?;
+    let user_agent = client.initialize()?;
+    let resume = client.resume(&binding.thread_id)?;
+    validate_tuple(binding, &user_agent, &resume)?;
+    client.turn_start(&binding.thread_id, message_id, rendered)
+}
+
+pub fn binding_from_receiver(receiver: &Value) -> Result<AppServerBinding, AppServerError> {
+    let app = receiver
+        .get("app_server")
+        .ok_or_else(|| AppServerError::ProtocolMismatch("missing app_server".to_string()))?;
+    Ok(AppServerBinding {
+        socket: required_str(app, "socket")?.to_string(),
+        thread_id: required_str(app, "thread_id")?.to_string(),
+        session_id: required_str(app, "session_id")?.to_string(),
+        cwd: required_str(app, "cwd")?.to_string(),
+        cli_version: required_str(app, "cli_version")?.to_string(),
+        bound_at: required_str(app, "bound_at")?.to_string(),
+    })
+}
+
+pub fn receiver_is_app_server(receiver: &Value) -> bool {
+    receiver.get("transport_kind").and_then(Value::as_str) == Some("codex_app_server")
+        || receiver.get("mode").and_then(Value::as_str) == Some("codex_app_server")
+}
+
+fn required_str<'a>(value: &'a Value, field: &str) -> Result<&'a str, AppServerError> {
+    value
+        .get(field)
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| AppServerError::ProtocolMismatch(format!("missing {field}")))
+}
+
+fn validate_tuple(
+    binding: &AppServerBinding,
+    user_agent: &str,
+    resume: &ThreadResume,
+) -> Result<(), AppServerError> {
+    if user_agent != binding.cli_version
+        || resume.thread_id != binding.thread_id
+        || resume.session_id != binding.session_id
+        || resume.cwd != binding.cwd
+    {
+        return Err(AppServerError::ThreadStale {
+            expected: json!({
+                "cli_version": binding.cli_version,
+                "thread_id": binding.thread_id,
+                "session_id": binding.session_id,
+                "cwd": binding.cwd,
+            }),
+            actual: json!({
+                "cli_version": user_agent,
+                "thread_id": resume.thread_id,
+                "session_id": resume.session_id,
+                "cwd": resume.cwd,
+            }),
+        });
+    }
+    Ok(())
+}
+
+fn check_socket_ownership(endpoint: &str) -> Result<(), AppServerError> {
+    let path = socket_path(endpoint)?;
+    let meta = std::fs::metadata(&path)
+        .map_err(|e| AppServerError::SocketUnreachable(format!("{}:{e}", path.display())))?;
+    if !meta.file_type().is_socket() {
+        return Err(AppServerError::SocketOwnershipInvalid(format!(
+            "not a unix socket: {}",
+            path.display()
+        )));
+    }
+    if meta.uid() != unsafe { libc::geteuid() } {
+        return Err(AppServerError::SocketOwnershipInvalid(format!(
+            "socket owner uid {} != current uid {}",
+            meta.uid(),
+            unsafe { libc::geteuid() }
+        )));
+    }
+    if meta.permissions().mode() & 0o002 != 0 {
+        return Err(AppServerError::SocketOwnershipInvalid(format!(
+            "socket is world-writable: {}",
+            path.display()
+        )));
+    }
+    Ok(())
+}
+
+fn socket_path(endpoint: &str) -> Result<PathBuf, AppServerError> {
+    let raw = endpoint.strip_prefix("unix://").unwrap_or(endpoint);
+    if raw.is_empty() {
+        return Err(AppServerError::SocketUnreachable(
+            "missing unix socket path".to_string(),
+        ));
+    }
+    Ok(PathBuf::from(raw))
+}
+
+struct ThreadResume {
+    thread_id: String,
+    session_id: String,
+    cwd: String,
+}
+
+struct AppServerClient {
+    stream: UnixStream,
+    next_id: u64,
+}
+
+impl AppServerClient {
+    fn connect(path: &Path) -> Result<Self, AppServerError> {
+        let mut stream = UnixStream::connect(path)
+            .map_err(|e| AppServerError::SocketUnreachable(format!("{}:{e}", path.display())))?;
+        stream
+            .set_read_timeout(Some(Duration::from_secs(10)))
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        stream
+            .set_write_timeout(Some(Duration::from_secs(10)))
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        let request = concat!(
+            "GET / HTTP/1.1\r\n",
+            "Host: localhost\r\n",
+            "Upgrade: websocket\r\n",
+            "Connection: Upgrade\r\n",
+            "Sec-WebSocket-Key: dGVhbS1hZ2VudC1jb2RleA==\r\n",
+            "Sec-WebSocket-Version: 13\r\n",
+            "\r\n"
+        );
+        stream
+            .write_all(request.as_bytes())
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        let response = read_http_response(&mut stream)?;
+        if !response.starts_with("HTTP/1.1 101") && !response.starts_with("HTTP/1.0 101") {
+            return Err(AppServerError::ProtocolMismatch(format!(
+                "websocket upgrade failed: {}",
+                response.lines().next().unwrap_or("")
+            )));
+        }
+        Ok(Self { stream, next_id: 1 })
+    }
+
+    fn initialize(&mut self) -> Result<String, AppServerError> {
+        let result = self.request(json!({
+            "method": "initialize",
+            "params": {
+                "clientInfo": {
+                    "name": "codex-appserver-team-agent",
+                    "title": "Team Agent",
+                    "version": env!("CARGO_PKG_VERSION")
+                },
+                "capabilities": {
+                    "experimentalApi": true,
+                    "requestAttestation": false
+                }
+            }
+        }))?;
+        let _ = self.notify(json!({"method": "initialized"}));
+        let user_agent = result
+            .get("userAgent")
+            .and_then(Value::as_str)
+            .filter(|value| !value.is_empty())
+            .ok_or(AppServerError::MissingUserAgent)?;
+        if !user_agent.to_ascii_lowercase().contains("codex") {
+            return Err(AppServerError::ProtocolMismatch(format!(
+                "unexpected userAgent: {user_agent}"
+            )));
+        }
+        Ok(user_agent.to_string())
+    }
+
+    fn resume(&mut self, thread_id: &str) -> Result<ThreadResume, AppServerError> {
+        let result = self.request(json!({
+            "method": "thread/resume",
+            "params": {"threadId": thread_id}
+        }))?;
+        let thread = result
+            .get("thread")
+            .ok_or_else(|| AppServerError::ProtocolMismatch("missing thread".to_string()))?;
+        let actual_thread_id = required_str(thread, "id")?.to_string();
+        let session_id = required_str(thread, "sessionId")?.to_string();
+        let cwd = result
+            .get("cwd")
+            .and_then(Value::as_str)
+            .or_else(|| thread.get("cwd").and_then(Value::as_str))
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| AppServerError::ProtocolMismatch("missing cwd".to_string()))?
+            .to_string();
+        Ok(ThreadResume {
+            thread_id: actual_thread_id,
+            session_id,
+            cwd,
+        })
+    }
+
+    fn turn_start(
+        &mut self,
+        thread_id: &str,
+        message_id: &str,
+        rendered: &str,
+    ) -> Result<AppServerSubmit, AppServerError> {
+        let result = self.request(json!({
+            "method": "turn/start",
+            "params": {
+                "threadId": thread_id,
+                "clientUserMessageId": message_id,
+                "input": [{
+                    "type": "text",
+                    "text": rendered,
+                    "text_elements": []
+                }]
+            }
+        }))?;
+        let turn = result
+            .get("turn")
+            .ok_or_else(|| AppServerError::ProtocolMismatch("missing turn".to_string()))?;
+        let turn_id = required_str(turn, "id")?.to_string();
+        let status = required_str(turn, "status")?.to_string();
+        if status != "inProgress" {
+            return Err(AppServerError::ProtocolMismatch(format!(
+                "turn/start returned status {status}"
+            )));
+        }
+        Ok(AppServerSubmit {
+            turn_id,
+            turn_status: status,
+        })
+    }
+
+    fn notify(&mut self, mut payload: Value) -> Result<(), AppServerError> {
+        if let Some(obj) = payload.as_object_mut() {
+            obj.remove("id");
+        }
+        write_ws_text(&mut self.stream, &payload.to_string())
+    }
+
+    fn request(&mut self, mut payload: Value) -> Result<Value, AppServerError> {
+        let method = payload
+            .get("method")
+            .and_then(Value::as_str)
+            .unwrap_or("unknown")
+            .to_string();
+        let id = self.next_id;
+        self.next_id = self.next_id.saturating_add(1);
+        if let Some(obj) = payload.as_object_mut() {
+            obj.insert("id".to_string(), json!(id));
+        }
+        write_ws_text(&mut self.stream, &payload.to_string())?;
+        loop {
+            let frame = read_ws_text(&mut self.stream)?;
+            let value: Value = serde_json::from_str(&frame)
+                .map_err(|e| AppServerError::Json(format!("{e}: {frame}")))?;
+            if let Some(method) = value.get("method").and_then(Value::as_str) {
+                if is_approval_method(method) {
+                    return Err(AppServerError::ApprovalUnsupported(method.to_string()));
+                }
+                continue;
+            }
+            if value.get("id").and_then(Value::as_u64) != Some(id) {
+                continue;
+            }
+            if let Some(error) = value.get("error") {
+                let message = error
+                    .get("message")
+                    .and_then(Value::as_str)
+                    .unwrap_or("app-server request failed")
+                    .to_string();
+                return match method.as_str() {
+                    "thread/resume" => Err(AppServerError::ThreadNotLive(message)),
+                    "turn/start" if looks_busy(&message) => {
+                        Err(AppServerError::LeaderBusy(message))
+                    }
+                    "turn/start" => Err(AppServerError::ThreadNotLive(message)),
+                    _ => Err(AppServerError::ProtocolMismatch(format!(
+                        "{method} failed: {message}"
+                    ))),
+                }
+            }
+            return value
+                .get("result")
+                .cloned()
+                .ok_or_else(|| AppServerError::ProtocolMismatch("missing result".to_string()));
+        }
+    }
+}
+
+fn is_approval_method(method: &str) -> bool {
+    method.contains("requestApproval")
+        || method.contains("requestUserInput")
+        || method.contains("elicitation/request")
+}
+
+fn looks_busy(message: &str) -> bool {
+    let lower = message.to_ascii_lowercase();
+    lower.contains("active turn") || lower.contains("already has") || lower.contains("busy")
+}
+
+fn read_http_response(stream: &mut UnixStream) -> Result<String, AppServerError> {
+    let mut data = Vec::new();
+    let mut buf = [0u8; 1];
+    while !data.ends_with(b"\r\n\r\n") {
+        stream
+            .read_exact(&mut buf)
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        data.push(buf[0]);
+        if data.len() > 64 * 1024 {
+            return Err(AppServerError::ProtocolMismatch(
+                "oversized websocket handshake".to_string(),
+            ));
+        }
+    }
+    Ok(String::from_utf8_lossy(&data).to_string())
+}
+
+fn write_ws_text(stream: &mut UnixStream, text: &str) -> Result<(), AppServerError> {
+    let payload = text.as_bytes();
+    let mut frame = vec![0x81];
+    if payload.len() < 126 {
+        frame.push(0x80 | payload.len() as u8);
+    } else if payload.len() <= u16::MAX as usize {
+        frame.push(0x80 | 126);
+        frame.extend_from_slice(&(payload.len() as u16).to_be_bytes());
+    } else {
+        frame.push(0x80 | 127);
+        frame.extend_from_slice(&(payload.len() as u64).to_be_bytes());
+    }
+    let mask = [0x54, 0x41, 0x47, 0x54];
+    frame.extend_from_slice(&mask);
+    for (idx, byte) in payload.iter().enumerate() {
+        frame.push(*byte ^ mask[idx % 4]);
+    }
+    stream
+        .write_all(&frame)
+        .map_err(|e| AppServerError::Io(e.to_string()))
+}
+
+fn read_ws_text(stream: &mut UnixStream) -> Result<String, AppServerError> {
+    loop {
+        let mut header = [0u8; 2];
+        stream
+            .read_exact(&mut header)
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        let opcode = header[0] & 0x0f;
+        if opcode == 0x8 {
+            return Err(AppServerError::ProtocolMismatch(
+                "websocket closed".to_string(),
+            ));
+        }
+        let masked = header[1] & 0x80 != 0;
+        let mut len = u64::from(header[1] & 0x7f);
+        if len == 126 {
+            let mut ext = [0u8; 2];
+            stream
+                .read_exact(&mut ext)
+                .map_err(|e| AppServerError::Io(e.to_string()))?;
+            len = u64::from(u16::from_be_bytes(ext));
+        } else if len == 127 {
+            let mut ext = [0u8; 8];
+            stream
+                .read_exact(&mut ext)
+                .map_err(|e| AppServerError::Io(e.to_string()))?;
+            len = u64::from_be_bytes(ext);
+        }
+        let mut mask = [0u8; 4];
+        if masked {
+            stream
+                .read_exact(&mut mask)
+                .map_err(|e| AppServerError::Io(e.to_string()))?;
+        }
+        let size = usize::try_from(len).map_err(|_| {
+            AppServerError::ProtocolMismatch("websocket frame too large".to_string())
+        })?;
+        let mut payload = vec![0u8; size];
+        stream
+            .read_exact(&mut payload)
+            .map_err(|e| AppServerError::Io(e.to_string()))?;
+        if masked {
+            for (idx, byte) in payload.iter_mut().enumerate() {
+                *byte ^= mask[idx % 4];
+            }
+        }
+        if opcode == 0x1 {
+            return Ok(String::from_utf8_lossy(&payload).to_string());
+        }
+    }
+}