feat(remote): phase α.5 — RemoteClient outbound implementation

Closes Phase α. RemoteClient is the crab-proto outbound side, symmetric
to the RemoteServer from α.4.b. Same wire, same lifecycle, different
direction: client calls connect(), runs initialize, then issues typed
session.create / session.attach / session.sendInput / session.cancel
round-trips and subscribes to server -> client session.event
notifications via a broadcast channel.

Module layout under crates/remote/src/client/:

- mod.rs     RemoteClient + dispatcher task. Cheap-to-clone (internally
             Arc<Inner>) so a TUI and a logger can both subscribe
             without fighting over the connection. Background task owns
             the WebSocket and routes:
               * outbound Request -> serialise + send + stash reply_tx
                 in a pending-map keyed by MessageId
               * inbound Response -> pull reply_tx from map, fulfil
                 oneshot so the waiting caller unblocks
               * inbound SESSION_EVENT notification -> broadcast::send
             close() signals the dispatcher to emit a WS close frame
             and exit; idempotent — second call returns AlreadyClosed.
- config.rs  ClientConfig { url, auth_token, client_info, request_timeout,
             event_buffer }. Durations serde as integer seconds so
             web / mobile clients reading the same config file get a
             predictable wire shape.
- error.rs   ClientError enum: InvalidUrl / InvalidAuthToken / Handshake /
             Transport / IncompatibleProtocol / ServerError /
             ConnectionClosed / Serde / AlreadyClosed. Wire-level and
             protocol-level failures split so callers can retry the
             former but not the latter.

lib.rs re-exports RemoteClient / ClientConfig / ClientError at the
crate root.

Integration tests in tests/client_roundtrip.rs (4 cases, all green)
exercise a real RemoteClient against a real RemoteServer:
  * handshake -> create -> backend event reaches client broadcast ->
    client send_input observed on backend inbound_rx -> cancel same
  * attach on a nonexistent session surfaces ServerError with the
    SessionNotFound code (-32003)
  * close is idempotent; second call returns AlreadyClosed
  * wrong JWT secret rejected at handshake (tungstenite bubbles the
    401 as Error::Http -> ClientError::Handshake)

Local totals for crab-remote: 33 unit + 4 server e2e + 4 client e2e =
41 green.

Phase α closes here. crab-proto now has both a working server and a
working client, validated against each other.

Author: lingcoder

crates/remote/src/client/config.rs

@@ -0,0 +1,97 @@
+//! Configuration for [`super::RemoteClient`].
+//!
+//! Split out so `cli` / `daemon` can load + validate config independently
+//! of actually opening a connection (e.g. `crab config check` can verify
+//! the shape without touching the network).
+
+use serde::{Deserialize, Serialize};
+use std::time::Duration;
+
+use crate::protocol::ClientInfo;
+
+/// Where and how to connect to a crab-proto server.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ClientConfig {
+    /// `ws://host:port/` or `wss://host:port/`. Path is ignored — the
+    /// server exposes the upgrade at `/` by convention.
+    pub url: String,
+
+    /// JWT issued by the target server's `jwt_secret`. Sent in the
+    /// `Authorization: Bearer <token>` header during the WebSocket
+    /// handshake.
+    pub auth_token: String,
+
+    /// How we identify ourselves in the `initialize` handshake. The
+    /// server logs this and can surface it in the TUI ("connected:
+    /// vscode-extension 1.2.3").
+    pub client_info: ClientInfo,
+
+    /// Round-trip timeout for request/response calls. Long enough for a
+    /// heavily-loaded server on a slow link; not so long that a dead
+    /// connection hangs indefinitely.
+    #[serde(with = "duration_secs")]
+    pub request_timeout: Duration,
+
+    /// Capacity of the `subscribe_events` broadcast channel. Overflows
+    /// are dropped on the slowest subscriber per tokio broadcast
+    /// semantics; 256 gives comfortable headroom for TUI rendering
+    /// while an agent streams tool-call output.
+    pub event_buffer: usize,
+}
+
+impl ClientConfig {
+    /// Build a minimal config from endpoint + token. Sets `client_info`
+    /// to `(crab, CARGO_PKG_VERSION)` and `request_timeout` to 30s.
+    pub fn new(url: impl Into<String>, auth_token: impl Into<String>) -> Self {
+        Self {
+            url: url.into(),
+            auth_token: auth_token.into(),
+            client_info: ClientInfo {
+                name: "crab".into(),
+                version: env!("CARGO_PKG_VERSION").into(),
+            },
+            request_timeout: Duration::from_secs(30),
+            event_buffer: 256,
+        }
+    }
+}
+
+/// Serde helper mirroring the one in `server::config` — `Duration` on
+/// the wire is integer seconds.
+mod duration_secs {
+    use serde::{Deserialize, Deserializer, Serializer};
+    use std::time::Duration;
+
+    pub fn serialize<S: Serializer>(d: &Duration, ser: S) -> Result<S::Ok, S::Error> {
+        ser.serialize_u64(d.as_secs())
+    }
+
+    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<Duration, D::Error> {
+        let secs = u64::deserialize(de)?;
+        Ok(Duration::from_secs(secs))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn new_populates_client_info_and_defaults() {
+        let c = ClientConfig::new("ws://127.0.0.1:4180/", "tok");
+        assert_eq!(c.client_info.name, "crab");
+        assert!(!c.client_info.version.is_empty());
+        assert_eq!(c.request_timeout, Duration::from_secs(30));
+        assert_eq!(c.event_buffer, 256);
+    }
+
+    #[test]
+    fn serde_roundtrip_uses_integer_seconds() {
+        let c = ClientConfig::new("ws://x/", "t");
+        let json = serde_json::to_string(&c).unwrap();
+        assert!(json.contains("\"requestTimeout\":30"));
+        let back: ClientConfig = serde_json::from_str(&json).unwrap();
+        assert_eq!(back.request_timeout, c.request_timeout);
+    }
+}

crates/remote/src/client/error.rs

@@ -0,0 +1,41 @@
+//! Errors surfaced by [`super::RemoteClient`].
+//!
+//! Wire-level (envelope / JSON-RPC) failures are kept separate from
+//! protocol-level (server returned an error reply) failures so consumers
+//! can retry the former but not the latter.
+
+use crate::protocol::JsonRpcError;
+
+#[derive(Debug, thiserror::Error)]
+pub enum ClientError {
+    #[error("invalid server URL: {0}")]
+    InvalidUrl(String),
+
+    #[error("invalid auth token (not HTTP-header-safe): {0}")]
+    InvalidAuthToken(String),
+
+    #[error("WebSocket handshake failed: {0}")]
+    Handshake(#[source] tokio_tungstenite::tungstenite::Error),
+
+    #[error("WebSocket read/write error: {0}")]
+    Transport(#[source] tokio_tungstenite::tungstenite::Error),
+
+    #[error("server speaks protocol {server}, client speaks {client}")]
+    IncompatibleProtocol { server: String, client: String },
+
+    #[error("server replied with JSON-RPC error {}: {}", .0.code, .0.message)]
+    ServerError(JsonRpcError),
+
+    #[error("connection closed before the response arrived (pending id {0})")]
+    ConnectionClosed(u64),
+
+    #[error("failed to (de)serialise {what}: {source}")]
+    Serde {
+        what: &'static str,
+        #[source]
+        source: serde_json::Error,
+    },
+
+    #[error("client is already closed")]
+    AlreadyClosed,
+}