comodor 0.19.2__tar.gz → 0.20.0__tar.gz

{comodor-0.19.2 → comodor-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: comodor
-Version: 0.19.2
+Version: 0.20.0
 Summary: Comodor — a self-improving terminal coding agent with a Rich TUI
 Project-URL: Homepage, https://comodor.ai
 Project-URL: Repository, https://github.com/ifekri/Comodor
@@ -75,7 +75,7 @@ falling or not. A number, not a claim.
 | **Never surprises you** | Reading is silent. Writing shows a diff. Commands ask. Every change is checkpointed and `/undo` puts it back. [→](docs/safety.md) |
 | **Drives a real browser** | One that runs JavaScript, keeps cookies and can log in — not a page fetcher. [→](docs/browser.md) |
 | **Uses your screen** | Mouse and keyboard in any application, with a halo showing where it is about to click before it clicks. [→](docs/computer.md) |
-| **Runs on your phone** | Telegram or WhatsApp, the whole interface as buttons, running in the background whether or not a terminal is open. Read-only until you say otherwise. [→](docs/telegram.md) · [→](docs/whatsapp.md) |
+| **Runs on your phone** | Telegram, Slack or WhatsApp — the whole interface as buttons, running in the background whether or not a terminal is open. Read-only until you say otherwise. [→](docs/telegram.md) · [→](docs/slack.md) · [→](docs/whatsapp.md) |
 | **Runs a model locally** | Pick one, watch it download, use it with the network unplugged. No key, no account. [→](docs/local-models.md) |
 | **Lives in your editor** | Speaks ACP, so VS Code, JetBrains and Zed drive it from their own panels. [→](docs/acp.md) |
 | **Follows your procedures** | Write a skill once; it loads when the work matches. 147 ready to install. [→](docs/skills.md) |
@@ -174,6 +174,7 @@ Esc        stop it                F3         cycle mode
 | [What it can do](docs/tools.md) | The 13 tools, and when it uses each |
 | [Safety and permissions](docs/safety.md) | What it asks, and what it never does |
 | [From your phone](docs/telegram.md) | The Telegram bot, and who it answers |
+| [From Slack](docs/slack.md) | Socket Mode — five minutes, and no public address |
 | [From WhatsApp](docs/whatsapp.md) | The Cloud API — longer to set up; Telegram does the same thing |
 | [Models on your machine](docs/local-models.md) | Downloading one, running it offline |
 | [Configuration](docs/configuration.md) | Every setting, and what wins |

{comodor-0.19.2 → comodor-0.20.0}/README.md

@@ -48,7 +48,7 @@ falling or not. A number, not a claim.
 | **Never surprises you** | Reading is silent. Writing shows a diff. Commands ask. Every change is checkpointed and `/undo` puts it back. [→](docs/safety.md) |
 | **Drives a real browser** | One that runs JavaScript, keeps cookies and can log in — not a page fetcher. [→](docs/browser.md) |
 | **Uses your screen** | Mouse and keyboard in any application, with a halo showing where it is about to click before it clicks. [→](docs/computer.md) |
-| **Runs on your phone** | Telegram or WhatsApp, the whole interface as buttons, running in the background whether or not a terminal is open. Read-only until you say otherwise. [→](docs/telegram.md) · [→](docs/whatsapp.md) |
+| **Runs on your phone** | Telegram, Slack or WhatsApp — the whole interface as buttons, running in the background whether or not a terminal is open. Read-only until you say otherwise. [→](docs/telegram.md) · [→](docs/slack.md) · [→](docs/whatsapp.md) |
 | **Runs a model locally** | Pick one, watch it download, use it with the network unplugged. No key, no account. [→](docs/local-models.md) |
 | **Lives in your editor** | Speaks ACP, so VS Code, JetBrains and Zed drive it from their own panels. [→](docs/acp.md) |
 | **Follows your procedures** | Write a skill once; it loads when the work matches. 147 ready to install. [→](docs/skills.md) |
@@ -147,6 +147,7 @@ Esc        stop it                F3         cycle mode
 | [What it can do](docs/tools.md) | The 13 tools, and when it uses each |
 | [Safety and permissions](docs/safety.md) | What it asks, and what it never does |
 | [From your phone](docs/telegram.md) | The Telegram bot, and who it answers |
+| [From Slack](docs/slack.md) | Socket Mode — five minutes, and no public address |
 | [From WhatsApp](docs/whatsapp.md) | The Cloud API — longer to set up; Telegram does the same thing |
 | [Models on your machine](docs/local-models.md) | Downloading one, running it offline |
 | [Configuration](docs/configuration.md) | Every setting, and what wins |

{comodor-0.19.2 → comodor-0.20.0}/docs/README.md

@@ -42,6 +42,7 @@ ends with the agent doing something useful.
 | | |
 |---|---|
 | [From your phone](telegram.md) | The Telegram bot: pairing, the buttons, and who it answers |
+| [From Slack](slack.md) | Socket Mode — five minutes, no public address, and it answers in threads |
 | [From WhatsApp](whatsapp.md) | The Cloud API — about twenty minutes and technical. Telegram does the same in one |
 | [Models on your machine](local-models.md) | Downloading one, running it offline, adding to the list |
 | [Questions](questions.md) | The form it puts up when a request reads two ways |

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.19.2'
-__version_tuple__ = version_tuple = (0, 19, 2)
+__version__ = version = '0.20.0'
+__version_tuple__ = version_tuple = (0, 20, 0)
 
 __commit_id__ = commit_id = None

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/browser/cdp.py

@@ -24,17 +24,16 @@ Two things about the protocol that are easy to get wrong:
 
 from __future__ import annotations
 
-import base64
 import json
-import os
-import socket
-import struct
 import threading
 import time
 import urllib.error
 import urllib.request
 from typing import Any, Callable
 
+from ..net.ws import WebSocket as _WebSocket
+from ..net.ws import WebSocketError
+
 DEFAULT_TIMEOUT = 30.0
 #: Long enough for a slow page on a slow machine, short enough that a hung
 #: renderer does not hold the turn until the agent's own deadline.
@@ -50,135 +49,34 @@ class BrowserError(RuntimeError):
 # --------------------------------------------------------------------------- #
 
 
-class WebSocket:
-    """RFC 6455, client side, and only the parts CDP uses.
+class WebSocket(_WebSocket):
+    """The general client, with the browser's vocabulary on its failures.
 
-    No extensions, no compression, no continuation frames on send: CDP sends
-    JSON text and so do we. Fragmented *incoming* frames are reassembled,
-    because a large accessibility tree arrives in pieces.
+    The frame handling moved to `net.ws` when Slack's Socket Mode became a
+    second caller for it. This keeps the errors saying "the browser", because
+    everything above catches `BrowserError` and a person reading a traceback
+    about a websocket is a person who has to work out which websocket.
     """
 
     def __init__(self, url: str, timeout: float = DEFAULT_TIMEOUT) -> None:
-        _, _, rest = url.partition("://")
-        hostport, _, path = rest.partition("/")
-        host, _, port = hostport.partition(":")
         try:
-            self._socket = socket.create_connection((host, int(port or 80)),
-                                                    timeout=timeout)
-        except OSError as error:
-            raise BrowserError(f"could not connect to the browser: {error}") from error
-        self._socket.settimeout(timeout)
-
-        key = base64.b64encode(os.urandom(16)).decode()
-        self._socket.sendall(
-            f"GET /{path} HTTP/1.1\r\n"
-            f"Host: {hostport}\r\n"
-            f"Upgrade: websocket\r\n"
-            f"Connection: Upgrade\r\n"
-            f"Sec-WebSocket-Key: {key}\r\n"
-            f"Sec-WebSocket-Version: 13\r\n\r\n".encode())
-
-        header = b""
-        while b"\r\n\r\n" not in header:
-            chunk = self._socket.recv(1)
-            if not chunk:
-                raise BrowserError("the browser closed the connection during the handshake")
-            header += chunk
-            if len(header) > 8192:
-                raise BrowserError("the browser sent a handshake we cannot read")
-        if b" 101" not in header.split(b"\r\n")[0]:
-            raise BrowserError(f"the browser refused the upgrade: "
-                               f"{header.split(chr(13).encode())[0][:80]!r}")
-        self._buffer = b""
-        self._send_lock = threading.Lock()
-
-    # -- frames ------------------------------------------------------------ #
+            super().__init__(url, timeout=timeout)
+        except WebSocketError as error:
+            raise BrowserError(
+                f"could not connect to the browser: {error}") from error
 
     def send(self, text: str) -> None:
-        payload = text.encode()
-        frame = bytearray([0x81])                 # FIN + text
-        length = len(payload)
-        if length < 126:
-            frame.append(0x80 | length)
-        elif length < 65536:
-            frame.append(0x80 | 126)
-            frame += struct.pack(">H", length)
-        else:
-            frame.append(0x80 | 127)
-            frame += struct.pack(">Q", length)
-        # A client must mask; a server must not. Chrome enforces both.
-        mask = os.urandom(4)
-        frame += mask
-        frame += bytes(byte ^ mask[index % 4] for index, byte in enumerate(payload))
-        with self._send_lock:
-            try:
-                self._socket.sendall(bytes(frame))
-            except OSError as error:
-                raise BrowserError(f"the browser went away: {error}") from error
+        try:
+            super().send(text)
+        except WebSocketError as error:
+            raise BrowserError(f"the browser went away: {error}") from error
 
     def receive(self) -> str:
-        """One complete message, reassembled if it arrived in fragments."""
-        parts: list[bytes] = []
-        while True:
-            first, second = self._exactly(2)
-            final = bool(first & 0x80)
-            opcode = first & 0x0F
-            length = second & 0x7F
-            if length == 126:
-                length = struct.unpack(">H", self._exactly(2))[0]
-            elif length == 127:
-                length = struct.unpack(">Q", self._exactly(8))[0]
-            mask = self._exactly(4) if second & 0x80 else b""
-            payload = self._exactly(length)
-            if mask:
-                payload = bytes(byte ^ mask[index % 4]
-                                for index, byte in enumerate(payload))
-
-            if opcode == 0x8:                     # close
-                raise BrowserError("the browser closed the connection")
-            if opcode == 0x9:                     # ping -> pong
-                self._pong(payload)
-                continue
-            if opcode == 0xA:                     # pong
-                continue
-
-            parts.append(payload)
-            if final:
-                return b"".join(parts).decode("utf-8", "replace")
-
-    def _pong(self, payload: bytes) -> None:
-        frame = bytearray([0x8A, 0x80 | len(payload)])
-        mask = os.urandom(4)
-        frame += mask
-        frame += bytes(byte ^ mask[index % 4] for index, byte in enumerate(payload))
-        with self._send_lock:
-            try:
-                self._socket.sendall(bytes(frame))
-            except OSError:
-                pass
-
-    def _exactly(self, count: int) -> bytes:
-        while len(self._buffer) < count:
-            try:
-                chunk = self._socket.recv(65536)
-            except socket.timeout as error:
-                raise BrowserError("the browser stopped answering") from error
-            except OSError as error:
-                raise BrowserError(f"the browser went away: {error}") from error
-            if not chunk:
-                raise BrowserError("the browser closed the connection")
-            self._buffer += chunk
-        taken, self._buffer = self._buffer[:count], self._buffer[count:]
-        return taken
-
-    def settimeout(self, timeout: float) -> None:
-        self._socket.settimeout(timeout)
-
-    def close(self) -> None:
         try:
-            self._socket.close()
-        except OSError:
-            pass
+            return super().receive()
+        except WebSocketError as error:
+            raise BrowserError(
+                f"the browser closed the connection: {error}") from error
 
 
 # --------------------------------------------------------------------------- #

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/channels/__init__.py

@@ -65,9 +65,25 @@ def _whatsapp_ready(settings: Any) -> tuple[bool, str]:
     return True, ""
 
 
+def _slack_ready(settings: Any) -> tuple[bool, str]:
+    if not settings.bot_token:
+        return False, ("Not connected. `comodor slack connect` sets up the "
+                       "workspace and the two tokens.")
+    if not settings.app_token:
+        return False, ("No app-level token, so Socket Mode cannot open — "
+                       "`comodor slack connect --app-token xapp-…`")
+    if not settings.allowed:
+        return False, ("Nobody is paired, so it would answer nobody. "
+                       "`comodor slack pair` first.")
+    return True, ""
+
+
 TELEGRAM = Channel(name="telegram", label="Telegram", section="telegram",
                    ready=_telegram_ready)
 WHATSAPP = Channel(name="whatsapp", label="WhatsApp", section="whatsapp",
                    ready=_whatsapp_ready)
 
-CHANNELS = (TELEGRAM, WHATSAPP)
+SLACK = Channel(name="slack", label="Slack", section="slack",
+                ready=_slack_ready)
+
+CHANNELS = (TELEGRAM, WHATSAPP, SLACK)

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/cli.py

@@ -104,6 +104,7 @@ def build_parser() -> argparse.ArgumentParser:
     from .local.commands import register as register_local
     from .mcp.commands import register as register_mcp
     from .skills.commands import register as register_skills
+    from .slack.commands import register as register_slack
     from .telegram.commands import register as register_telegram
     from .web.commands import register as register_web
     from .whatsapp.commands import register as register_whatsapp
@@ -112,6 +113,7 @@ def build_parser() -> argparse.ArgumentParser:
     register_local(sub)
     register_telegram(sub)
     register_whatsapp(sub)
+    register_slack(sub)
     register_skills(sub)
     register_web(sub)
     register_acp(sub)
@@ -828,6 +830,10 @@ def main(argv: list[str] | None = None) -> int:
         from .whatsapp.commands import run as run_whatsapp
 
         return run_whatsapp(config, args)
+    if args.command == "slack":
+        from .slack.commands import run as run_slack
+
+        return run_slack(config, args)
     if args.command == "skills":
         from .skills.commands import run as run_skills
 

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/config.py

@@ -460,6 +460,54 @@ def _digits(value: Any) -> str:
     return kept[2:] if kept.startswith("00") else kept
 
 
+@dataclass
+class SlackConfig:
+    """Reaching the agent from a Slack workspace.
+
+    Two tokens, because Slack has two kinds. The *bot* token does everything
+    the bot does in the workspace; the *app-level* token does one thing —
+    open the websocket Socket Mode runs on — and that is what keeps this
+    channel as easy to set up as Telegram. Slack's other delivery method posts
+    to a URL and would need a public HTTPS address, a certificate and a tunnel,
+    which is the whole of what makes WhatsApp hard.
+
+    A workspace can have hundreds of people in it, and this is an agent that
+    reads and writes somebody's files. `allowed` holds the Slack user ids it
+    answers; everybody else is ignored.
+    """
+
+    enabled: bool = False
+    #: `xoxb-…`, from OAuth & Permissions after the app is installed.
+    bot_token: str = ""
+    #: `xapp-…`, from Basic Information → App-Level Tokens, scope
+    #: `connections:write`. Only ever used to open the socket.
+    app_token: str = ""
+    #: Slack user ids — `U…` or `W…`. Not display names: a display name can be
+    #: changed by the person holding it, and an id cannot.
+    allowed: list[str] = field(default_factory=list)
+    #: Whether a turn started from Slack may edit files and run commands.
+    allow_writes: bool = False
+    #: Seconds a pairing code stays valid.
+    pair_window: int = 300
+    #: The workspace it was connected to, remembered so `status` can name it
+    #: without a round trip.
+    team: str = ""
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "enabled": self.enabled,
+            "bot_token": self.bot_token,
+            "app_token": self.app_token,
+            "allowed": list(self.allowed),
+            "allow_writes": self.allow_writes,
+            "pair_window": self.pair_window,
+            "team": self.team,
+        }
+
+    def may(self, user_id: str) -> bool:
+        return bool(user_id) and str(user_id) in {str(x) for x in self.allowed}
+
+
 @dataclass
 class MCPConfig:
     """Servers, and the master switch over all of them."""
@@ -507,7 +555,7 @@ DEFAULT_DENY: tuple[str, ...] = (
 #: for its whole existence: `headless: false` in a config file did nothing and
 #: said nothing.
 SECTIONS = ("ui", "agent", "gateway", "learning", "skills", "safety",
-            "browser", "computer", "telegram", "whatsapp")
+            "browser", "computer", "telegram", "whatsapp", "slack")
 
 
 @dataclass
@@ -523,6 +571,7 @@ class Config:
     computer: ComputerConfig = field(default_factory=ComputerConfig)
     telegram: TelegramConfig = field(default_factory=TelegramConfig)
     whatsapp: WhatsAppConfig = field(default_factory=WhatsAppConfig)
+    slack: SlackConfig = field(default_factory=SlackConfig)
     mcp: MCPConfig = field(default_factory=MCPConfig)
     safety: SafetyConfig = field(default_factory=SafetyConfig)
     providers: dict[str, ProviderConfig] = field(default_factory=dict)
@@ -816,14 +865,16 @@ PROJECT_SETTABLE: dict[str, frozenset[str] | None] = {
     # uses is useful; a project starting a process is not its decision. The
     # master switch is deliberately absent.
     "mcp": frozenset({"servers"}),
-    # `browser`, `computer`, `telegram` and `whatsapp` are deliberately absent,
+    # `browser`, `computer`, `telegram`, `whatsapp` and `slack` are
+    # deliberately absent,
     # and this is the note for whoever is tempted to add them. A project that
     # could set `browser.executable` names a binary for the agent to launch.
     # One that could set `computer.enabled` asks the machine it was just cloned
     # onto for its mouse and keyboard. One that could set `telegram.allowed` or
-    # `whatsapp.allowed` adds its author to the list of people who may drive
-    # that machine from a phone — and unlike the other two, nothing on screen
-    # would ever show it happening. None of the four belongs to a repository.
+    # `whatsapp.allowed` or `slack.allowed` adds its author to the list of
+    # people who may drive that machine from a phone — and unlike the other
+    # two, nothing on screen would ever show it happening. None of the five
+    # belongs to a repository.
 }
 
 

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/doctor.py

@@ -104,7 +104,7 @@ def run_checks(config: Config, online: bool = True) -> Report:
               _check_saved_provider, _check_model, _check_spend_limit,
               _check_brain,
               _check_search_index, _check_skills, _check_leftovers, _check_mcp,
-              _check_telegram, _check_whatsapp]
+              _check_telegram, _check_whatsapp, _check_slack]
     if online:
         checks.append(_check_version)
 
@@ -480,6 +480,10 @@ def _check_whatsapp(config: Config) -> Finding | None:
     return _check_phone(config, "whatsapp")
 
 
+def _check_slack(config: Config) -> Finding | None:
+    return _check_phone(config, "slack")
+
+
 def _check_phone(config: Config, name: str) -> Finding | None:
     """A bot that is set up and answering nobody, or not running at all.
 
@@ -493,7 +497,8 @@ def _check_phone(config: Config, name: str) -> Finding | None:
     if channel is None:
         return None
     settings = channel.settings(config)
-    if not getattr(settings, "token", ""):
+    if not (getattr(settings, "token", "")
+            or getattr(settings, "bot_token", "")):
         return None
 
     ok, why = channel.can_run(config)

{comodor-0.19.2 → comodor-0.20.0}/src/comodor/help.py

@@ -55,6 +55,7 @@ SECTIONS: list[tuple[str, list[tuple[str, str]]]] = [
     ("Reach further", [
         ("comodor web", "use it from a browser, here or on a server"),
         ("comodor telegram start", "drive it from your phone, all buttons"),
+        ("comodor slack start", "the same, in a Slack workspace"),
         ("comodor whatsapp start", "the same, from a WhatsApp number"),
         ("comodor skills browse", "procedures it follows when the work calls for them"),
         ("comodor mcp list", "tools from Model Context Protocol servers"),
@@ -222,6 +223,33 @@ must be configured before it will start.
 In Docker:  docker compose up   and open the address it prints.
 Full guide: docs/web.md"""),
 
+    "slack": ("From Slack", """\
+  comodor slack manifest           the app definition to paste into Slack
+  comodor slack connect            the two tokens, checked as you paste them
+  comodor slack pair               a one-time code that adds your account
+  comodor slack start -b           run it detached from this terminal
+  comodor slack status             what is set, who may talk, is it running
+
+About five minutes. Slack takes an app *manifest*, so the app is one paste
+rather than a page of checkboxes - name, scopes, events and Socket Mode all
+switched on already.
+
+Socket Mode is why this needs no public address: the app opens a websocket
+outward rather than being posted to. That is the whole difference between this
+and WhatsApp, which needs a certificate and a tunnel.
+
+Two tokens, and they are not interchangeable:
+
+  xoxb-...   the bot token, from OAuth & Permissions. Does the work.
+  xapp-...   the app-level token, from Basic Information, scope
+             connections:write. Opens the socket, and nothing else.
+
+In a channel it answers when mentioned; in a direct message, always. It answers
+a fixed list of accounts and nobody else - a workspace can have hundreds of
+people in it, and this reads and writes your files.
+
+Full guide: docs/slack.md"""),
+
     "whatsapp": ("From WhatsApp", """\
   comodor whatsapp connect         guided: links each page, checks each value
   comodor whatsapp webhook         what to paste into Meta's dashboard

comodor-0.20.0/src/comodor/net/ws.py

@@ -0,0 +1,210 @@
+"""RFC 6455, client side, over TCP or TLS.
+
+Lifted out of the browser package, where it was written for Chrome's debugging
+protocol and grew a second caller: Slack's Socket Mode, which is a websocket
+the app opens outward so that no public URL is needed. Two hand-rolled
+implementations of the same frame format in one wheel would be one too many —
+and the browser's could not have served, because it speaks plain TCP and Slack
+is `wss://`.
+
+Only what a client actually needs. No extensions, no compression, no
+fragmented *sends* — every caller here sends JSON text, which fits one frame.
+Incoming fragments are reassembled, because a large accessibility tree and a
+busy Slack workspace both arrive in pieces.
+
+The masking is not optional and is a common thing to get wrong: a client must
+mask every frame it sends and a server must not mask what it sends back.
+Chrome enforces the first and Slack enforces both.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import socket
+import ssl
+import struct
+import threading
+from urllib.parse import urlsplit
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class WebSocketError(RuntimeError):
+    """The connection failed, refused the upgrade, or went away."""
+
+
+class WebSocket:
+    """One connection. Thread-safe to send on, single-reader to receive."""
+
+    def __init__(self, url: str, timeout: float = DEFAULT_TIMEOUT,
+                 headers: dict[str, str] | None = None) -> None:
+        parts = urlsplit(url)
+        secure = parts.scheme in ("wss", "https")
+        host = parts.hostname or ""
+        port = parts.port or (443 if secure else 80)
+        path = parts.path or "/"
+        if parts.query:
+            path = f"{path}?{parts.query}"
+
+        try:
+            raw = socket.create_connection((host, port), timeout=timeout)
+        except OSError as error:
+            raise WebSocketError(f"could not connect to {host}: {error}") \
+                from error
+
+        if secure:
+            try:
+                context = ssl.create_default_context()
+                raw = context.wrap_socket(raw, server_hostname=host)
+            except OSError as error:
+                raw.close()
+                raise WebSocketError(f"TLS to {host} failed: {error}") from error
+
+        self._socket = raw
+        self._socket.settimeout(timeout)
+        self._buffer = b""
+        self._send_lock = threading.Lock()
+
+        key = base64.b64encode(os.urandom(16)).decode()
+        request = [
+            f"GET {path} HTTP/1.1",
+            f"Host: {host}" + ("" if port in (80, 443) else f":{port}"),
+            "Upgrade: websocket",
+            "Connection: Upgrade",
+            f"Sec-WebSocket-Key: {key}",
+            "Sec-WebSocket-Version: 13",
+        ]
+        for name, value in (headers or {}).items():
+            request.append(f"{name}: {value}")
+        try:
+            self._socket.sendall(("\r\n".join(request) + "\r\n\r\n").encode())
+        except OSError as error:
+            raise WebSocketError(f"could not send the handshake: {error}") \
+                from error
+
+        header = b""
+        while b"\r\n\r\n" not in header:
+            try:
+                chunk = self._socket.recv(1)
+            except OSError as error:
+                raise WebSocketError(f"handshake failed: {error}") from error
+            if not chunk:
+                raise WebSocketError("closed during the handshake")
+            header += chunk
+            if len(header) > 8192:
+                raise WebSocketError("the server sent a handshake we cannot read")
+
+        first = header.split(b"\r\n")[0]
+        if b" 101" not in first:
+            raise WebSocketError(f"the upgrade was refused: {first[:120]!r}")
+
+    # -- frames ------------------------------------------------------------ #
+
+    def send(self, text: str) -> None:
+        payload = text.encode()
+        frame = bytearray([0x81])                 # FIN + text
+        length = len(payload)
+        if length < 126:
+            frame.append(0x80 | length)
+        elif length < 65536:
+            frame.append(0x80 | 126)
+            frame += struct.pack(">H", length)
+        else:
+            frame.append(0x80 | 127)
+            frame += struct.pack(">Q", length)
+        mask = os.urandom(4)
+        frame += mask
+        frame += bytes(byte ^ mask[index % 4]
+                       for index, byte in enumerate(payload))
+        with self._send_lock:
+            try:
+                self._socket.sendall(bytes(frame))
+            except OSError as error:
+                raise WebSocketError(f"the connection went away: {error}") \
+                    from error
+
+    def receive(self) -> str:
+        """One complete message, reassembled if it arrived in fragments."""
+        parts: list[bytes] = []
+        while True:
+            first, second = self._exactly(2)
+            final = bool(first & 0x80)
+            opcode = first & 0x0F
+            length = second & 0x7F
+            if length == 126:
+                length = struct.unpack(">H", self._exactly(2))[0]
+            elif length == 127:
+                length = struct.unpack(">Q", self._exactly(8))[0]
+            mask = self._exactly(4) if second & 0x80 else b""
+            payload = self._exactly(length)
+            if mask:
+                payload = bytes(byte ^ mask[index % 4]
+                                for index, byte in enumerate(payload))
+
+            if opcode == 0x8:                     # close
+                raise WebSocketError("the server closed the connection")
+            if opcode == 0x9:                     # ping -> pong
+                self._pong(payload)
+                continue
+            if opcode == 0xA:                     # pong
+                continue
+
+            parts.append(payload)
+            if final:
+                return b"".join(parts).decode("utf-8", "replace")
+
+    def _pong(self, payload: bytes) -> None:
+        frame = bytearray([0x8A, 0x80 | len(payload)])
+        mask = os.urandom(4)
+        frame += mask
+        frame += bytes(byte ^ mask[index % 4]
+                       for index, byte in enumerate(payload))
+        with self._send_lock:
+            try:
+                self._socket.sendall(bytes(frame))
+            except OSError:
+                pass
+
+    def ping(self, payload: bytes = b"") -> None:
+        """Say we are still here.
+
+        Slack closes a socket it has not heard from, and its own pings are not
+        enough on a quiet workspace — a bot nobody messaged for an hour is
+        exactly the case that must survive.
+        """
+        frame = bytearray([0x89, 0x80 | len(payload)])
+        mask = os.urandom(4)
+        frame += mask
+        frame += bytes(byte ^ mask[index % 4]
+                       for index, byte in enumerate(payload))
+        with self._send_lock:
+            try:
+                self._socket.sendall(bytes(frame))
+            except OSError as error:
+                raise WebSocketError(f"the connection went away: {error}") \
+                    from error
+
+    def _exactly(self, count: int) -> bytes:
+        while len(self._buffer) < count:
+            try:
+                chunk = self._socket.recv(65536)
+            except socket.timeout as error:
+                raise WebSocketError("the server stopped answering") from error
+            except OSError as error:
+                raise WebSocketError(f"the connection went away: {error}") \
+                    from error
+            if not chunk:
+                raise WebSocketError("the server closed the connection")
+            self._buffer += chunk
+        taken, self._buffer = self._buffer[:count], self._buffer[count:]
+        return taken
+
+    def settimeout(self, timeout: float) -> None:
+        self._socket.settimeout(timeout)
+
+    def close(self) -> None:
+        try:
+            self._socket.close()
+        except OSError:
+            pass