clawmates/infrastructurehandoff/IMPLEMENTATION.md

Clawmates Frontend — Implementation & Wiring Handoff

Audience: the build agent (or engineer) integrating these screens into the Clawmates platform (the Rust workspace + Next.js app) and feeding them live from the durable runner.

What this package is: every Clawmates screen as a self-contained HTML file, plus a dependency-free real-time bridge and client adapter that make them update live. Read this file once, top to bottom, before wiring anything. Everything runs offline in demo mode with synthetic data, so you can see each screen breathe before touching the backend.

---

0. Package layout

handoff/
├── IMPLEMENTATION.md         ← this file
├── README.md                 ← 60-second start
├── install.sh                ← idempotent installer (Node check, static server, .env)
├── .env.example              ← copy → .env for live mode
├── screens/                  ← the UI. Open any .dc.html directly in a browser — no build step.
│   ├── Clawmates World.dc.html
│   ├── Clawmates Observe.dc.html
│   ├── Clawmates Dashboard.dc.html
│   ├── Clawmates Infrastructure.dc.html
│   ├── Clawmates Auth.dc.html
│   ├── Clawmates Landing.dc.html
│   └── support.js            ← the .dc runtime (MUST sit next to the .dc.html files)
└── realtime/
    ├── server.mjs            ← demo + live SSE bridge (Node ≥20, zero deps)
    ├── clawmates-live.js     ← browser client adapter → window.ClawmatesLive
    └── events.schema.json    ← the Clawmates Event Taxonomy (the contract)

What a .dc.html file is

Each screen is a Design Component: a single HTML file whose markup + a small logic class are rendered by the bundled support.js runtime. There is no build step and no npm install to view them — open the file in a browser, or serve the screens/ folder statically. support.js must sit beside the .dc.html files (it does, in screens/).

To edit a screen's behavior you change two regions inside the file: the <x-dc>…</x-dc> template (markup, inline-styled) and the class Component extends DCLogic { … } block (state + a renderVals() that returns the values the template binds to). All live data flows into a screen by calling this.setState(...) from a ClawmatesLive.on(...) handler — see §3.

---

1. The screens

Screen	Purpose	Primary live inputs (see §3 taxonomy)
World	The "Large World" map in three formations: Hierarchy (org▸company▸team▸claw tree), Flat (peer mesh), Live (Gource-style convergence on a <canvas>).	topology.update, world.touch, node.activity, agent.status
Observe	Linked observation deck — Agent close-up (live reasoning + the agent's live computer screen) and System mission-control (both claws, comms, routines, telemetry).	agent.task.update, agent.reasoning.delta, agent.computer.frame, agent.message, telemetry, routine.update, door.request
Dashboard	Tiered admin: org→company→team→claw with topology morph + the per-claw "anatomy" (brain compartments) and the agent's computer.	agent.status, topology.update, routine.update
Infrastructure	Fleet management. Local & Tailscale first (host health cards, tailnet device list, 3-step Connect-a-host wizard), then Cloud (AWS/GCP/Apple silicon/Hetzner/DigitalOcean connect + provision).	host.health, host.status, tailscale.devices, cloud.runner (see §5)
Auth	Clerk-style sign-in / sign-up with Google / Apple / GitHub OAuth + email.	n/a (wire to Clerk — see §6)
Landing	Marketing page (deploy ladder, 12 topologies, §15 safety, self-host).	static

Canonical entry point for the product app: World, Observe, Dashboard, and Infrastructure are the in-product surfaces. Auth gates them; Landing is public.

1a. Per-screen integration seams (where synthetic becomes live)

Each screen ships with a built-in synthetic animation so it looks alive offline. To make it real, register handlers in the logic class' componentDidMount() and feed setState. The exact seams:

• World → _startLive() (the canvas engine). It holds targets[] (project/service/event nodes) and agents[] whose .target is currently chosen on a random timer. Replace the random retarget with world.touch: on each event, set the matching agent's .target to the index of nodeId and force a beam; the node-heat/glow already keys off "hot". Rebuild targets[] from topology.update. Hierarchy/Flat node lists also come from topology.update.
• Observe → Agent mode. Bind the WORKING-ON-NOW card to agent.task.update (replace), the REASONING STREAM to agent.reasoning.delta (append), the live computer screen to agent.computer.frame (replace). The door toast binds to door.request / door.resolve.
• Observe → System mode & Dashboard. Telemetry pills ← telemetry; comms list ← agent.message; routines/loops ← routine.update; status dots ← agent.status.
• Infrastructure. Host health cards ← host.health + host.status; the Tailscale device list ← tailscale.devices; cloud runners ← cloud.runner. The Connect-a-host and Connect-a-provider wizards are driven by the daemon-pairing and provisioning APIs in §5.

Every seam is a few lines: ClawmatesLive.on('world.touch', e => engine.touch(e.agentId, e.nodeId)). No markup changes — you are feeding values into components that already exist.

---

2. Run it (60 seconds, no backend)

chmod +x install.sh && ./install.sh
# Terminal 1 — synthetic event bridge
(cd realtime && CLAWMATES_MODE=demo node server.mjs)
# Terminal 2 — serve the screens
caddy file-server --root ./screens --listen :8080      # or: npx serve ./screens -l 8080

Open http://localhost:8080/Clawmates%20World.dc.html?live=http://localhost:8420/live, switch to the Live formation, and the agents converge on events streamed from the bridge. Without ?live=, each screen runs its built-in synthetic animation (safe fallback). The ?live= param (or window.CLAWMATES_LIVE_URL) is read by clawmates-live.js.

---

3. Real-time architecture & the Event Taxonomy

The runner emits many internal events; the bridge (realtime/server.mjs) normalizes them into a small, stable taxonomy and fans them out as one SSE feed. The browser only ever sees these. Full JSON Schema: realtime/events.schema.json. Human summary:

Agent work — agent.status {agentId,status,role} · agent.task.update {agentId,taskId,title,elapsedMs,steps[]} · agent.reasoning.delta {agentId,text} (append) · agent.computer.frame {agentId,app,url?,lines[]}.

Tools, doors & §15 — agent.tool.call {agentId,tool,target,doorRequired} · door.request {doorId,agentId,action,target,summary} · door.resolve {doorId,decision,by}.

Collaboration & world — agent.message {fromAgentId,toAgentId,text,ts} · world.touch {agentId,nodeId,kind} (the Gource retarget) · node.activity {nodeId,label,kind,heat} · topology.update {formation,nodes[],edges[]}.

System — telemetry {tokensPerMin,costPerHr,loops,doorsPending} · routine.update {routineId,name,kind,owner,schedule?,progress?,state}.

Infrastructure (new — see §5) — host.status {hostId,status} · host.health {hostId,cpu,ram,memPressure,disk,load,containers} · tailscale.devices {tailnet,devices[]} · cloud.runner {provider,id,region,size,status,cpu,ram,agents,costPerHr}.

The integration seam in the bridge

normalize(evt, payload) in server.mjs translates one raw runner event → zero+ taxonomy events. The upstream event names there (turn.started, tool.invoked, runner.telemetry, …) are placeholders — reconcile them with the actual cm-api SSE shapes. Start by mapping just world.touch, agent.status, and telemetry; that alone brings World and the top bars alive. Add the rest incrementally. Unknown events are ignored, so the bridge is forward-compatible.

The client adapter (clawmates-live.js)

Include it in a screen (or inject via the Next proxy). It opens an EventSource, dispatches each event to ClawmatesLive.on(type, fn) handlers and a window CustomEvent('clawmates:<type>'), and replays the last value per stateful key so a late-loading screen paints current state immediately (mirrors the runner's checkpoint-resume). If no live URL is set, it is inert.

Security invariant — carry it through. The bridge is read-only on the runner stream. It must never hold or forward secret-broker credentials, and it must expose no door-approval endpoint to the browser. Door approvals stay on the authenticated cm-api path; the bridge only renders that a door is pending so the UI can badge it.

---

4. Wiring to cm-api [INTEGRATES WITH cm-api]

Live mode points the bridge at the runner's SSE gateway and exchanges a session for a bearer token, exactly like the Next.js /api proxy. .env:

CLAWMATES_MODE=live
CM_API_SSE_URL=http://127.0.0.1:8080/v1/runs/stream   # cm-api streaming gateway
CM_API_TOKEN=sk-...                                    # read-only, scoped to run events
LIVE_PORT=8420
LIVE_ALLOWED_ORIGINS=http://localhost:8080             # the screens' origin (CORS)

Deployment shapes:

• A) Standalone: serve screens/ with Caddy; run the bridge as its own systemd service beside the product. Good for an ops/observability surface.
• B) In-app (tightest): mount each screen in the Next.js app via <iframe src="/viz/world?live=/api/live"> and proxy /api/live to the bridge so it inherits the app's session→bearer swap and CORS.

systemd unit for the bridge (read-only, hardened):

# /etc/systemd/system/clawmates-live.service
[Unit]
Description=Clawmates Live Visualization Bridge
After=network.target
[Service]
WorkingDirectory=/opt/clawmates/handoff/realtime
EnvironmentFile=/opt/clawmates/handoff/.env
ExecStart=/usr/bin/node server.mjs
Restart=always
RestartSec=2
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target

---

5. Infrastructure wiring (Local & Tailscale first, then Cloud)

The Infrastructure screen is the most backend-coupled. It maps directly onto the daemon + tailnet + cloud-provisioning model.

5a. Local hosts — the clawmates-node daemon

The Connect a host wizard (Install → Connect → Verify) is the UI for the daemon-pairing flow:

1. Install. cm-api mints a one-time token and returns the install command shown in the wizard: clawmates-node --server https://clawmates.work --token <token> (Docker should be present on the node so it can run agents). The curl … /install.sh | bash one-liner needs the binary hosted; for now cargo build --release -p clawmates-node once, then run the line.
2. Connect. The daemon dials home over an outbound WSS (NAT-friendly, no inbound port). When cm-api sees the socket, emit host.status {hostId,status:"connected"} + the host specs; the wizard flips to Connected.
3. Verify. cm-api runs the built-in check (uname + docker version) on the node; stream the result so the wizard shows the verification and the host is added to the fleet.

Thereafter stream host.health (CPU / RAM / mem pressure / disk / load / containers) on an interval → the live host cards. If the host is on Tailscale, include its 100.x IP so the card can show the copyable ssh <tailscale-ip> target.

5b. Tailscale network — fleet metrics

The Tailscale network panel maps to: Infra → Fleet → Tailscale network → Connect. The user pastes their tailnet (e.g. your-org.ts.net) + a Tailscale API key; cm-api polls the Tailscale API and emits tailscale.devices {tailnet, devices:[{name,ip,os,status,seen}]} → the live device list (online / last-seen / IP / OS). Note the daemon can also join the tailnet for the operator (tailscale up --ssh, or pass --tailscale-authkey <key> to have the daemon run it) — --ssh is what gives keyless, ACL-gated SSH (ensure the tailnet ACL permits SSH via an ssh rule / tag).

5c. Cloud providers — provision runners

The Cloud screen connects AWS / GCP / Apple silicon / Hetzner / DigitalOcean. The connect wizard maps to:

1. Credentials → stored in the secret broker over its private socket; they never enter agent code or any sandbox. (Same invariant as §3.)
2. Region + instance size → the provision request.
3. Provision → cm-api launches a VM from an image with clawmates-node baked in; on boot it dials home over WSS (no inbound port) and the §15 sandbox profile is applied. Emit cloud.runner updates → the live cloud-runner cards (CPU/RAM, agent count, hourly cost). Deprovision terminates the VM.

Ordering: ship Local & Tailscale first (own hardware, zero inbound exposure); Cloud is the next rung and reuses the same daemon + WSS + §15 model — it's the same fleet, just provisioned for you.

---

6. Auth (Clerk)

The Auth screen is a themed Clerk surface (Google / Apple / GitHub OAuth + email, sign-in ↔ sign-up toggle). To make it real, replace the static markup with Clerk's <SignIn> / <SignUp> components and pass an appearance theme that reuses the screen's tokens (near-black #08080a, coral #ff6f61, the rounded inputs and primary button). cm-api auth is local by default or clerk at runtime — match whichever the deployment uses. The bridge/screens never see auth secrets.

---

7. Verification checklist

1. node realtime/server.mjs (demo) prints Live bridge on http://localhost:8420/live · mode=demo.
2. curl -N http://localhost:8420/live streams event: … lines that don't stop.
3. World ?live=… → Live shows particles retargeting in sync with the world.touch lines in the curl output (not the smooth random demo motion).
4. Kill the bridge mid-stream → the screen shows reconnect, then resumes (EventSource auto-reconnect + adapter replay).
5. [live] Point at cm-api, trigger a run, and confirm telemetry numbers in the top bar move and a real door.request raises the toast in Observe.
6. [infra] Run the daemon install line on a test node → host.status connected → health card appears → ssh <tailscale-ip> target resolves.

---

8. Build order (recommended)

1. Bridge normalize() → reconcile upstream event names with cm-api; map world.touch, agent.status, telemetry first.
2. World Live engine ← world.touch + topology.update. (Biggest payoff, smallest change.)
3. Observe Agent ← agent.task.update / agent.reasoning.delta / agent.computer.frame; door toast.
4. Infrastructure ← daemon pairing (§5a), tailnet metrics (§5b), then cloud provisioning (§5c).
5. Auth ← Clerk components with the theme tokens.
6. Promote the bridge from read-only mirror to a typed gateway with backpressure + per-tenant scoping; add a time-scrubber to replay the runner's checkpoint log (Gource-style playback).

---

The .dc.html files in screens/ are the source of truth for the UI. This document plus realtime/ is everything needed to serve them and make them breathe with live agent activity. Keep support.js next to the screens.