feat: OpenMax (CWS) channel plugin — full implementation

README.md

@@ -2,21 +2,36 @@
 
 OpenMax (CWS) channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) — connects an OpenClaw agent to the OpenMax/CWS workspace over WebSocket.
 
-Part of the OpenMax agent-runtime integration family (`openclaw-openmax`, `hermes-openmax`, `claude-openmax`, `codex-openmax`), built on the shared `@coco-xyz/cws-agent-sdk`.
+Part of the OpenMax agent-runtime integration family (`openclaw-openmax`, `hermes-openmax`, `claude-openmax`, `codex-openmax`), built on the shared `@openmaxai/openmax-agent-sdk`.
 
-> **Status: skeleton.** CWS wiring is blocked on the first publish of
-> `@coco-xyz/cws-agent-sdk`. All SDK call sites are marked `TODO(sdk)` in
-> `index.ts`.
+> **Status: verified end-to-end against a live CWS environment** on
+> `@openmaxai/openmax-agent-sdk` (alpha line, see package.json) — DM round-trip, owner
+> auto-bind, group mention gating, smart mode, image/file attachments,
+> reply chunking, and disconnect/sync recovery.
+
+## Features
+
+- 💬 **DM + group conversations** — with per-group access policy (`allowlist` / `open` / `disabled`)
+- 🎯 **Mention gating** — `mention` (respond only when @-mentioned), `smart` (model decides, `[SKIP]` stays silent), or `silent` (context only); structured mentions plus text `@name` fallback
+- 👤 **Owner auto-bind** — the first DM binds the sender as owner and persists it; owner @mentions bypass the group allowlist
+- 🖼️ **Media** — inbound images/files are downloaded and fed to the model (`ctx.MediaPaths`), including media in quoted replies
+- 🧵 **Context blocks** — group history, quoted replies, and smart-mode hints framed for the agent
+- ⚡ **System Member priority** — urgent/high platform signals steer into (or optionally interrupt) a busy session
+- 🔁 **No silent message loss** — SDK inbox-ledger dedupe + `/sync` catch-up across disconnects and restarts
+- 📤 **Outbound** — @mention canonicalization, markdown auto-detect, 3000-char chunking; works from the gateway and the `openclaw message send` CLI
 
 ## Architecture
 
 ```
 CWS Server
-    │  WebSocket (auth, heartbeat, reconnect — via @coco-xyz/cws-agent-sdk)
+    │  WebSocket + REST (auth chain, heartbeat, reconnect, /sync catch-up,
+    │  dedupe, access policy — via @openmaxai/openmax-agent-sdk CwsAgentBridge)
     │
 openclaw-openmax (this plugin)
-    │  inbound:  CWS message → access policy → OpenClaw Channel Router → Agent Session
-    │  outbound: agent reply → routeOutboundMessage() → CWS conversation
+    │  inbound:  InboundDelivery.deliver() → group-context/quote/smart-hint blocks
+    │            → OpenClaw Channel Router → Agent Session
+    │            (System Member priority → per-message queue-mode override)
+    │  outbound: agent reply → @mention canonicalization + chunking → bridge.send()
 ```
 
 Same two-layer pattern as [openclaw-hxa-connect](https://github.com/coco-xyz/openclaw-hxa-connect): the SDK owns the protocol/connection, the plugin owns routing and policy.
@@ -26,7 +41,7 @@ Same two-layer pattern as [openclaw-hxa-connect](https://github.com/coco-xyz/ope
 1. Clone into your OpenClaw extensions directory:
    ```bash
    cd ~/.openclaw/extensions
-   git clone https://github.com/coco-xyz/openclaw-openmax.git openmax
+   git clone https://github.com/openmaxai/openclaw-openmax.git openmax
    cd openmax
    npm install
    ```
@@ -42,13 +57,15 @@ Same two-layer pattern as [openclaw-hxa-connect](https://github.com/coco-xyz/ope
      "channels": {
        "openmax": {
          "enabled": true,
-         "serverUrl": "wss://cws.example.com/agent",
+         "coreUrl": "https://cws.example.com",
+         "wsUrl": "wss://cws.example.com/ws",
          "agentToken": "agent_...",
          "agentName": "yourbot",
          "orgId": "your-org-id",
          "access": {
-           "dmPolicy": "open",
-           "groupPolicy": "open"
+           "dmPolicy": "owner",
+           "groupPolicy": "allowlist",
+           "groups": {}
          }
        }
      }
@@ -60,9 +77,51 @@ Same two-layer pattern as [openclaw-hxa-connect](https://github.com/coco-xyz/ope
 
 3. Restart OpenClaw.
 
+## Connecting to OpenMax (CWS)
+
+The plugin needs four values from your CWS workspace: `coreUrl`, `wsUrl`, an
+agent `agentToken` (api_key), and the `orgId`. Getting them takes two calls —
+you need a **single-use invitation** (ID + token) from your org admin first:
+
+```bash
+CWS=https://cws.example.com
+
+# 1. Register a new agent identity — returns identity_id + api_key (shown ONCE)
+curl -s -X POST "$CWS/auth/register/agent" -H "Content-Type: application/json" -d '{}'
+
+# 2. Exchange the api_key for an access token, then accept the invitation
+ACCESS_TOKEN=$(curl -s -X POST "$CWS/auth/agent/token" \
+  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" -d '{}' \
+  | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['access_token'])")
+curl -s -X POST "$CWS/api/v1/invitations/<INVITATION_ID>/accept" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
+  -d '{"token": "<INVITATION_TOKEN>"}'
+# → {"data":{"member_id":"…","org_id":"…"}}
+```
+
+Put the `api_key` (as `agentToken`) and `org_id` (as `orgId`) into
+`channels.openmax`, restart, and watch the logs for:
+
+```
+[openmax] [token] exchange ok org=<org_id>
+[openmax] [ticket] org=<org_id> requesting ws-ticket
+[openmax] [ws] org=<org_id> open
+```
+
+Then DM the agent from the CWS workspace — the **first DM auto-binds the sender
+as owner** (`dmPolicy: owner`) and the agent replies in the conversation. Group
+behavior is opt-in: add each group to `access.groups` with a `mode`
+(`mention` / `smart` / `silent`); without an entry, only owner @mentions get
+through (`groupPolicy: allowlist`).
+
+Full walkthrough (including environments behind Cloudflare Access, e.g.
+cws-int) in [docs/onboarding.md](./docs/onboarding.md).
+
 ## Design notes
 
-See [docs/design.md](./docs/design.md) (Chinese) for the CWS ↔ OpenClaw semantic mapping and open questions.
+See [docs/design.en.md](./docs/design.en.md) (English) / [docs/design.md](./docs/design.md) (Chinese) for the CWS ↔ OpenClaw semantic mapping, the zylos-openmax capability alignment matrix, and open questions.
+
+Behavioral semantics (access policy, mention gating, group context, reconnect catch-up) are aligned with **zylos-openmax** (`zylos-coco-workspace`), the existing production CWS integration.
 
 ## License