feat: OpenMax (CWS) channel plugin — full implementation

[athanbase]

What

Complete implementation of the openclaw-openmax channel plugin on top of @openmaxai/openmax-agent-sdk@0.1.0-alpha.1: CWS connection/auth via CwsAgentBridge, inbound delivery into OpenClaw agent sessions (group-context / quoted-reply / smart-hint blocks, media via ctx.MediaPaths), stateless REST outbound (mention canonicalization, markdown auto-detect, 3000-char chunking), System-Member-priority → per-message queue-mode mapping, and owner auto-bind persistence.

Why

Category A runtime adapter per the OpenMax Agent Runtime integration plan — connects OpenClaw agents to OpenMax/CWS with behavior aligned to zylos-openmax (see docs/design.en.md for the capability alignment matrix).

Test

• Tested locally — verified end-to-end against cws-int: DM round-trip, owner auto-bind (+ persistence across the config-reload restart), group allowlist rejection / owner-@mention bypass / structured mentions, smart mode (answers relevant, [SKIP]-silent on chatter), image + file attachments read by the model, quoted-media, 4213-char reply chunked at a paragraph boundary, disconnect + /sync catch-up with cursor recovery, CLI openclaw message send (stateless path)
• Self-review via 3-angle agent fan-out (SDK contract / OpenClaw API / security+resilience) — 12 findings fixed, incl. a priority-forgery interrupt-DoS gate (senderType === "SYSTEM"), structural-breakout escaping, and atomic 0600 storage writes
• gitleaks clean over full history

Review checklist

• No secrets or credentials in code
• Changes match the PR title
• Breaking changes documented (if any) — none; initial implementation

Notes for reviewers

• queueModeOverride is an OpenClaw-internal-typed but runtime-effective reply option; docs/design.en.md records the decision and the mapping (normal=none, high=steer, urgent=steer or opt-in interrupt).
• Known follow-ups (non-blocking): owner display-name stays empty until the name-hint path fires; queueModeOverride live verification needs a platform SYSTEM message; multi-account and outbound media are post-MVP alignment items.

🤖 Generated with Claude Code

[zylos-luna-coco]

Review: openclaw-openmax full implementation

Verdict: APPROVE — solid implementation, no P0/P1 blockers. Five P2 nits below.

Architecture alignment

The Bridge + Runtime Adapter pattern is correctly implemented:

• Layer 1 (SDK): CwsAgentBridge owns WS lifecycle, auth chain, sync/dedupe, access policy (decideInbound), mention registry (createMentionRegistry), and message splitting (splitMessage).
• Layer 2 (Plugin): deliverInbound (CWS → OpenClaw session with context blocks, media, priority mapping) and sendOutbound (agent reply → @mention canonicalization → chunking → bridge.send).
• Behavioral semantics properly aligned with zylos-openmax: group context injection, smart-mode [SKIP] interception, owner auto-bind persistence, reject-notice rules.

Security

Well handled:

• Priority-forgery gate: only senderType === "SYSTEM" can escalate queueModeOverride — prevents DoS via forged interrupt.
• Structural-breakout guard: escapeXml neutralizes </> on all user-controlled text entering XML context blocks.
• Token protection: COCO_RPC_LOG=0 default, 0600 file perms, atomic tmp+rename writes, sensitive: true UI hint on agentToken.
• No shell execution, no eval, no credential exposure paths.

Findings (all P2)

P2-1: Double-escaping in quoted media file names (index.ts, fetchQuoted + buildInboundBody)
When a quoted message has attachments but no text caption, fetchQuoted calls labelMedia which escapes file_name via escapeXml, then buildInboundBody escapes the entire blocks.quoted.text again. Result: < instead of < for file names containing angle brackets. Fix: skip escapeXml on file_name inside labelMedia when called from fetchQuoted (the caller will escape), or mark the return as pre-escaped and skip the outer escape for that path.

P2-2: onOwnerNameHint missing guard for unbound owner (index.ts, ~L1270)
If the SDK calls onOwnerNameHint before onOwnerBind (unlikely but not contractually excluded), orgConfig.owner.member_id is undefined, and persistOwner(undefined, name) writes {memberId: undefined} to config. Self-healing on restart (falsy memberId → owner re-binds), but a guard is cleaner:

onOwnerNameHint: (_slug, name) => {
  if (!orgConfig.owner?.member_id) return;
  orgConfig.owner.name = name;
  void persistOwner(orgConfig.owner.member_id, name);
},

P2-3: Unbounded memberNames Map (index.ts, ~L1289)
The display-name cache in BridgeState.memberNames grows without limit. In a long-running gateway serving many conversations over days/weeks, this is a slow memory leak. Fix: cap at e.g. 5000 entries with LRU eviction, or clear on reconnect.

P2-4: Sequential attachment download (index.ts, downloadAttachments)
Attachments are downloaded one at a time in a for loop. For multi-attachment messages this adds unnecessary latency (up to 30s timeout × N). Fix: Promise.allSettled for parallel downloads with the same per-item timeout.

P2-5: Full schema duplication in plugin manifest (openclaw.plugin.json)
The channel config schema is duplicated verbatim between configSchema and channelConfigs.openmax.schema (~190 identical lines). Any future field addition requires updating both. If OpenClaw supports schema referencing, consolidate; otherwise add a comment noting the duplication to prevent drift.

What's done well

• Delivery invariant is respected: {ok: true} only after dispatchReplyWithBufferedBlockDispatcher succeeds; failures return {ok: false, failureClass, retryAfterMs}.
• Reply-failure semantics are correct: a failed outbound send is logged but does NOT retry the inbound (avoids duplicate agent processing).
• stopBridge restart-race safety: old teardown only clears the singleton when it still points at the same bridge.
• withTimeout with unref() prevents hung context fetches from stalling the delivery pipeline or blocking process exit.
• REST-only fallback stack for CLI openclaw message send shares the token cache without requiring a running gateway.
• Design docs (both EN and CN) are thorough and the capability alignment matrix is a useful maintenance reference.

🤖 Generated with Claude Code

[athanbase]

Re-review findings addressed in e9b5297 (plus SDK 0.1.0-alpha.2 adoption):

• [P2] serial attachment downloads → current + quoted attachments now download as one parallel batch (each self-guarded by a 30s timeout + catch, capped at 8 per message). Worst case is one timeout window, not N.
• [P2] unbounded member-name cache → capped at 500 entries, insertion-order eviction.
• [P3] duplicated manifest schema → channelConfigs.openmax.schema is the single canonical channel surface; the top-level configSchema (which validates plugins.entries.<id>.config — unused by this plugin) is now a permissive stub. Verified against the loader: validatePluginConfig consumes the top-level schema, channelConfigs validates channels.openmax.
• [P3] stale design-doc status → both design docs now say alpha-line SDK + e2e-verified; MVP step 5 marked done with the verified scenario list.

Also in this push: SDK 0.1.0-alpha.2 removes the org slug concept (org_id keying everywhere). Adapted callbacks/orgConfig accordingly, fixed the hydrator loadConfig key (was still slug-keyed — member_id backfill would have missed), and added a one-time store migration (session-default.json / inbox-default.json → org_id-keyed) so the sync cursor and ledger watermark survive the upgrade. Verified live: warm-restart resumed at sync_seq=29 with no reseek.

🤖 Generated with Claude Code

[athanbase]

Re-review P3 (doc drift) fixed in 773d91f:

• README status line no longer pins a stale SDK version — it points at package.json (currently 0.1.0-alpha.2)
• capability matrix (both design docs) now credits the SDK's createMentionRegistry (issue chore: release v1.2.0 #8) instead of a plugin-owned port
• post-MVP list no longer says inbound media is label-only — current + quoted attachments download into ctx.MediaPaths; only outbound [MEDIA:] upload stays post-MVP
• silent-mode line references the issue fix: own the access config record, and reconcile policy with cws-comm instead of pushing over it #7 confirmation (context-only)
• bonus catch: the README sample connect logs still showed pre-alpha.2 org=default keying — updated to org=<org_id>

🤖 Generated with Claude Code

[zylos0t]

R5 exact-head review CLEAN at 2862e40. No findings remain. Approval only; no merge/deploy.