ClawXP
From Feb 10, 2025

Changemap

A detailed day-by-day record of every protocol decision, SDK milestone, and infrastructure improvement since ClawXP was first conceived.

ProtocolSDKInfraDocsSecurityIntegrationFix
Feb 21, 2025Day 12

Next.js 15 + React 19 upgrade, Playground launch

Docs
  • Upgraded from Next.js 14 to 15.1.9 - async params, full RSC support
  • Upgraded React 18 → 19 to match Next.js 15 bundled runtime
  • Migrated next-mdx-remote from v4.4.1 (CVE) to v6.0.0 (RSC API)
  • Rewrote MDXContent as a server component - serialize step eliminated
  • Launched interactive Playground page for real-time protocol testing
  • Full brand rename: Clawde3Protocol → ClawXP across all files
  • New footer with 4-column layout, legal pages, and OpenClaw attribution
  • Added OpenClaw integration section to homepage with SVG flow diagram
Feb 20, 2025Day 11

v0.1.0 public release

Protocol
  • Tagged v0.1.0 of @clawxp/protocol and @clawxp/sdk
  • Published both packages to npm under the @clawxp scope
  • Documentation site went live at clawxp.xyz
  • Added OpenGraph + Twitter card metadata for all marketing pages
  • Launched sitemap.ts with priority/frequency for all routes
Feb 19, 2025Day 10

Documentation site & content

Docs
  • Wrote all seven core MDX documentation pages (introduction through troubleshooting)
  • Built DocsSidebar with mobile drawer and active-link highlighting
  • Built DocsTOC with IntersectionObserver-based active-heading tracking
  • Implemented prev/next navigation between docs pages
  • Added Callout component for info/warning/error/success callouts
  • Configured rehype-slug and rehype-highlight for heading anchors and syntax coloring
Feb 18, 2025Day 9

First OpenClaw integration milestone

Integration
  • Established integration contract with OpenClaw agent runtime (openclaw.ai)
  • ClawXP selected as real-time pub/sub transport for OpenClaw live streams
  • Implemented `openclaw:agent-stream` channel convention
  • Added stream-mode subscription for model output / thought streaming
  • Integration test suite: verified sub-100ms end-to-end for agent events
Feb 17, 2025Day 8

Rate limiting & backpressure

Infra
  • Implemented token-bucket rate limiting per connection (configurable burst/refill)
  • Added per-channel publish rate limits via server config
  • Backpressure: server pauses stream when client buffer exceeds watermark
  • Graceful degradation: drops oldest buffered datagrams under memory pressure
  • Added `connection.ratelimited` event emitted to SDK on throttle
Feb 16, 2025Day 7

Redis adapter for horizontal scaling

Infra
  • Built pluggable adapter interface: `IClawXPAdapter` with `publish()` / `subscribe()`
  • Implemented `InMemoryAdapter` as the default zero-dependency adapter
  • Implemented `RedisAdapter` using ioredis pub/sub for cross-node fan-out
  • Adapter hot-swap: replace in-memory with Redis by changing one config line
  • Added `adapter.connected` and `adapter.error` health events
  • Tested 10-node Redis cluster with 50k concurrent connections
Feb 15, 2025Day 6

@clawxp/sdk client library (v0.1.0-alpha)

SDK
  • Built ClawXPClient class with connection lifecycle management
  • Implemented `subscribe(channel, { mode, onMessage, onStale })` API
  • Implemented `publish(channel, data)` with automatic serialization
  • Added automatic reconnection with exponential backoff (max 30s)
  • Added automatic re-subscription after reconnect (restores all active subscriptions)
  • Client-side freshness tracking: drops datagrams with seq ≤ last-seen-seq
  • Added `connection.state` observable: connecting / connected / disconnecting / disconnected
  • TypeScript-first: full generics on message payloads
Feb 14, 2025Day 5

@clawxp/protocol package (v0.1.0-alpha)

Protocol
  • Packaged the server runtime as `@clawxp/protocol`
  • Exported `createServer(config)` factory and `ClawXPServer` class
  • Config schema: `port`, `adapter`, `auth`, `rateLimits`, `origins`
  • Added `server.on("connection")`, `server.on("subscribe")`, `server.on("publish")` hooks
  • Wrote integration test harness with in-process server + SDK client
Feb 13, 2025Day 4

Authentication system (JWT)

Security
  • Designed auth flow: client sends JWT in `Authorization: Bearer` header on connect
  • Server validates JWT signature, expiry, and audience before accepting connection
  • Implemented configurable `auth.verify(token)` hook for custom auth logic
  • Added per-channel ACL: `auth.can(claims, channel, action)` hook
  • Reject unauthorized connections with structured `4001 Unauthorized` close frame
  • Added HMAC-signed connection tokens as an alternative to JWT for simpler setups
Feb 12, 2025Day 3

WebSocket fallback + protocol wire format

Protocol
  • WebTransport (HTTP/3) primary path: each channel = independent QUIC stream
  • WebSocket fallback path: multiplexed channels over a single WS connection
  • SDK detects WebTransport support and falls back in < 50ms (no user impact)
  • Designed binary wire format: `[type:1][seq:4][channel-len:2][channel][payload]`
  • Message types: SUBSCRIBE / UNSUBSCRIBE / PUBLISH / ACK / ERROR / PING / PONG
  • Datagram mode: uses WebTransport datagrams or WS with `seq` for freshness
  • Stream mode: uses dedicated QUIC bidirectional stream or WS with ordering guarantee
Feb 11, 2025Day 2

Core QUIC/HTTP3 transport layer

Protocol
  • Evaluated h3, @fails-components/h3, and Node.js native QUIC (experimental)
  • Selected WebTransport API for browser clients - available in Chrome 97+, Edge 97+
  • Server uses Node.js QUIC with @webtransport/server (ponyfill)
  • Established connection lifecycle: CONNECT → AUTHENTICATE → READY
  • TLS 1.3 required on both transport paths (no downgrade)
  • Validated QUIC stream independence: slow channel does not block fast channel
Feb 10, 2025Day 1

Project inception & architecture design

Protocol
  • Identified problem: WebSocket connections share a single TCP stream - head-of-line blocking kills latency for mixed workloads
  • Decided on HTTP/3 (QUIC) as the primary transport layer
  • Defined two delivery semantics: reliable ordered streams vs. unreliable fast datagrams
  • Designed channel-based pub/sub API as the developer abstraction
  • Chose TypeScript for both server runtime and client SDK
  • Created monorepo structure: packages/protocol, packages/sdk, apps/web
  • Set up CI pipeline (GitHub Actions) with lint, typecheck, and integration tests

On the roadmap

○E2E encryption option (libsodium via sealed boxes)
○Go server implementation of @clawxp/protocol
○Presence channels (who is online in a channel)
○History replay - subscribe with `since: timestamp`
○Browser DevTools extension for ClawXP debugging
○OpenClaw skill for channel management via chat
○Cloudflare Workers edge adapter
○Grafana dashboard template for ClawXP metrics