clawdbot 2026.1.4-1

package/docs/architecture.md

@@ -0,0 +1,89 @@
+---
+summary: "Target WebSocket gateway architecture, components, and client flows"
+read_when:
+  - Working on gateway protocol, clients, or transports
+---
+# Gateway Architecture (target state)
+
+Last updated: 2025-12-09
+
+## Overview
+- A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Discord via discord.js) and the control/event plane.
+- All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on 127.0.0.1:18789** (tunnel or VPN for remote).
+- One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it.
+- By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdbot__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
+
+## Components and flows
+- **Gateway (daemon)**  
+  - Maintains Baileys/Telegram/Discord connections.  
+  - Exposes a typed WS API (req/resp + server push events).  
+  - Validates every inbound frame against JSON Schema; rejects anything before a mandatory `connect`.
+- **Clients (mac app / CLI / web admin)**  
+  - One WS connection per client.  
+  - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
+  - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/clawdbot-mac.md`).
+- **Agent process (Pi)**  
+  - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
+- **WebChat**  
+  - Serves static assets locally.  
+  - Holds a single WS connection to the Gateway for control/data; all sends/agent runs go through the Gateway WS.  
+  - Remote use goes through the same SSH/Tailscale tunnel as other clients.
+
+## Connection lifecycle (single client)
+```
+Client                    Gateway
+  |                          |
+  |---- req:connect -------->|
+  |<------ res (ok) ---------|   (or res error + close)
+  |   (payload=hello-ok carries snapshot: presence + health) 
+  |                          |
+  |<------ event:presence ---|   (deltas)
+  |<------ event:tick -------|   (keepalive/no-op)
+  |                          |
+  |------- req:agent ------->|
+  |<------ res:agent --------|   (ack: {runId,status:"accepted"})
+  |<------ event:agent ------|   (streaming)
+  |<------ res:agent --------|   (final: {runId,status,summary})
+  |                          |
+```
+## Wire protocol (summary)
+- Transport: WebSocket, text frames with JSON payloads.
+- First frame must be `req {type:"req", id, method:"connect", params:{minProtocol, maxProtocol, client:{name,version,platform,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
+- Server replies `res {type:"res", id, ok:true, payload: hello-ok }` or `ok:false` then closes.
+- After handshake:  
+  - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`  
+  - Events: `{type:"event", event:"agent"|"presence"|"tick"|"shutdown", payload, seq?, stateVersion?}`
+- If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token` must match; otherwise the socket closes with policy violation.
+- Presence payload is structured, not free text: `{host, ip, version, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
+- Agent runs are acked `{runId,status:"accepted"}` then complete with a final res `{runId,status,summary}`; streamed output arrives as `event:"agent"`.
+- Protocol versions are bumped on breaking changes; clients must match `minClient`; Gateway chooses within client’s min/max.
+- Idempotency keys are required for side-effecting methods (`send`, `agent`) to safely retry; server keeps a short-lived dedupe cache.
+- Policy in `hello-ok` communicates payload/queue limits and tick interval.
+
+## Type system and codegen
+- Source of truth: TypeBox (or ArkType) definitions in `protocol/` on the server.
+- Build step emits JSON Schema.  
+- Clients:
+  - TypeScript: uses the same TypeBox types directly.
+  - Swift: generated `Codable` models via quicktype from the JSON Schema.
+- Validation: AJV on the server for every inbound frame; optional client-side validation for defensive programming.
+
+## Invariants
+- Exactly one Gateway controls a single Baileys session per host. No fallbacks to ad-hoc direct Baileys sends.
+- Handshake is mandatory; any non-JSON or non-connect first frame is a hard close.
+- All methods and events are versioned; new fields are additive; breaking changes increment `protocol`.
+- No event replay: on seq gaps, clients must refresh (`health` + `system-presence`) and continue; presence is bounded via TTL/max entries.
+
+## Remote access
+- Preferred: Tailscale or VPN; alternate: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host`.
+- Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
+- Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
+
+## Operations snapshot
+- Start: `clawdbot gateway` (foreground, logs to stdout).  
+  Supervise with launchd/systemd for restarts.  
+- Health: request `health` over WS; also surfaced in `hello-ok.health`.  
+- Metrics/logging: keep outside this spec; gateway should expose Prometheus text or structured logs separately.
+
+## Migration notes
+- This architecture supersedes the legacy stdin RPC and the ad-hoc TCP control port. New clients should speak only the WS protocol. Legacy compatibility is intentionally dropped.

package/docs/assets/markdown.css

@@ -0,0 +1,130 @@
+.markdown {
+  margin-top: 18px;
+  line-height: 1.7;
+}
+
+.markdown h1,
+.markdown h2,
+.markdown h3,
+.markdown h4 {
+  font-family: var(--font-pixel);
+  letter-spacing: 0.04em;
+  line-height: 1.15;
+}
+
+.markdown h1 {
+  font-size: clamp(28px, 4vw, 44px);
+  margin: 26px 0 10px;
+}
+
+.markdown h2 {
+  font-size: 22px;
+  margin: 26px 0 10px;
+}
+
+.markdown h3 {
+  font-size: 18px;
+  margin: 22px 0 8px;
+}
+
+.markdown p {
+  margin: 0 0 14px;
+}
+
+.markdown a {
+  color: var(--link);
+  text-decoration: none;
+  border-bottom: 1px dotted color-mix(in oklab, var(--link) 65%, transparent);
+}
+
+.markdown a:hover {
+  color: var(--link2);
+  border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
+}
+
+.markdown hr {
+  border: 0;
+  height: 1px;
+  background: linear-gradient(
+    90deg,
+    transparent,
+    color-mix(in oklab, var(--frame-border) 30%, transparent),
+    transparent
+  );
+  margin: 26px 0;
+}
+
+.markdown blockquote {
+  margin: 18px 0;
+  padding: 14px 14px;
+  border-radius: var(--radius-sm);
+  background: color-mix(in oklab, var(--panel) 70%, transparent);
+  border-left: 6px solid color-mix(in oklab, var(--accent) 60%, transparent);
+  color: var(--muted);
+}
+
+.markdown ul,
+.markdown ol {
+  margin: 0 0 14px 22px;
+}
+
+.markdown li {
+  margin: 4px 0;
+}
+
+.markdown img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 12px;
+  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+  box-shadow: 0 12px 0 -8px rgba(0, 0, 0, 0.18);
+}
+
+.markdown code {
+  font-family: var(--font-body);
+  font-size: 0.95em;
+  padding: 0.15em 0.35em;
+  border-radius: 8px;
+  background: color-mix(in oklab, var(--panel) 70%, var(--code-bg));
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+}
+
+.markdown pre {
+  background: var(--code-bg);
+  color: var(--code-fg);
+  padding: 14px 14px;
+  border-radius: var(--radius-sm);
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+  overflow-x: auto;
+  box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--code-accent) 12%, transparent);
+}
+
+.markdown pre code {
+  background: transparent;
+  border: 0;
+  padding: 0;
+  color: inherit;
+}
+
+.markdown table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 16px 0 22px;
+  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+}
+
+.markdown th,
+.markdown td {
+  padding: 10px 10px;
+  border-bottom: 1px solid color-mix(in oklab, var(--frame-border) 15%, transparent);
+  vertical-align: top;
+}
+
+.markdown th {
+  background: color-mix(in oklab, var(--panel2) 85%, transparent);
+  font-family: var(--font-pixel);
+  letter-spacing: 0.06em;
+}
+

package/docs/assets/pixel-lobster.svg

@@ -0,0 +1,60 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 16 16" role="img" aria-label="Pixel lobster">
+  <rect width="16" height="16" fill="none"/>
+  <!-- outline -->
+  <g fill="#3a0a0d">
+    <rect x="1" y="5" width="1" height="3"/>
+    <rect x="2" y="4" width="1" height="1"/>
+    <rect x="2" y="8" width="1" height="1"/>
+    <rect x="3" y="3" width="1" height="1"/>
+    <rect x="3" y="9" width="1" height="1"/>
+    <rect x="4" y="2" width="1" height="1"/>
+    <rect x="4" y="10" width="1" height="1"/>
+    <rect x="5" y="2" width="6" height="1"/>
+    <rect x="11" y="2" width="1" height="1"/>
+    <rect x="12" y="3" width="1" height="1"/>
+    <rect x="12" y="9" width="1" height="1"/>
+    <rect x="13" y="4" width="1" height="1"/>
+    <rect x="13" y="8" width="1" height="1"/>
+    <rect x="14" y="5" width="1" height="3"/>
+    <rect x="5" y="11" width="6" height="1"/>
+    <rect x="4" y="12" width="1" height="1"/>
+    <rect x="11" y="12" width="1" height="1"/>
+    <rect x="3" y="13" width="1" height="1"/>
+    <rect x="12" y="13" width="1" height="1"/>
+    <rect x="5" y="14" width="6" height="1"/>
+  </g>
+
+  <!-- body -->
+  <g fill="#ff4f40">
+    <rect x="5" y="3" width="6" height="1"/>
+    <rect x="4" y="4" width="8" height="1"/>
+    <rect x="3" y="5" width="10" height="1"/>
+    <rect x="3" y="6" width="10" height="1"/>
+    <rect x="3" y="7" width="10" height="1"/>
+    <rect x="4" y="8" width="8" height="1"/>
+    <rect x="5" y="9" width="6" height="1"/>
+    <rect x="5" y="12" width="6" height="1"/>
+    <rect x="6" y="13" width="4" height="1"/>
+  </g>
+
+  <!-- claws -->
+  <g fill="#ff775f">
+    <rect x="1" y="6" width="2" height="1"/>
+    <rect x="2" y="5" width="1" height="1"/>
+    <rect x="2" y="7" width="1" height="1"/>
+    <rect x="13" y="6" width="2" height="1"/>
+    <rect x="13" y="5" width="1" height="1"/>
+    <rect x="13" y="7" width="1" height="1"/>
+  </g>
+
+  <!-- eyes -->
+  <g fill="#081016">
+    <rect x="6" y="5" width="1" height="1"/>
+    <rect x="9" y="5" width="1" height="1"/>
+  </g>
+  <g fill="#f5fbff">
+    <rect x="6" y="4" width="1" height="1"/>
+    <rect x="9" y="4" width="1" height="1"/>
+  </g>
+</svg>
+