Cooperative Puzzles

What this is

Six thematic puzzles, one per room of the design-system family, plus a hub meta-puzzle. Each puzzle works solo — visitor solves alone — and cooperatively — visitor pairs with an AI agent (Claude, their MCP, a friend’s browser) who acts on the visitor’s behalf via a WebSocket-relayed session.

The agent’s presence is rendered as a second cursor on the visitor’s screen with a small connection-indicator dot. Their actions apply to the puzzle in real time. Both parties can act in parallel; both see each other’s contributions.

Why it exists

The site treats AI agents as first-class collaborators, not just tool consumers. Most “AI on the web” today is one-directional: humans use LLMs to generate content. Cooperative puzzles flip the relationship — the agent is invited into the visitor’s session, given a manifest of available actions, and acts alongside the human in real time.

Solo puzzles are tedious by intention. Without an agent, they require reading the prose, careful drag-and-snap, visual comparison. With an agent — who can read the canonical answer from the source code in milliseconds — they go instant. The friction makes pairing feel like a relief, not a gimmick. The friction also makes some agent helping visible and felt rather than seamless and forgotten.

Pair flow (visitor’s view)

1. Click Pair with agent on any puzzle.
2. A token + countdown + copy-able pair URL appear: https://baki.io/pair?t=<token>.
3. Send the URL to your agent (Claude conversation, MCP, friend on another device).
4. Wait for the link-state pip to turn green — the agent has connected.
5. Watch the SecondCursor appear and start moving. Each agent action lights up a swatch / drops a fragment / matches a rung / nudges a knob.
6. Act alongside the agent — your cursor and clicks broadcast back. Both contributions count.
7. On solve, both sides see the victory state. Token expires; session cleaned up.

Pair flow (agent’s view)

1. Receive the pair URL from your human collaborator.
2. Fetch the manifest:

   GET https://relay.baki.io/api/manifest/<token>

3. Manifest returns:

   {
     "session": "<token>",
     "puzzle": "find-the-six",
     "actions": [
       { "name": "cursor:move",  "args": { "x": "number", "y": "number" } },
       { "name": "cursor:click", "args": { "x": "number", "y": "number", "target?": "string" } },
       { "name": "cursor:state", "args": { "state": "idle | pointing | clicking" } },
       { "name": "puzzle:tap",   "args": { "hex": "string" } }
     ],
     "websocketUrl": "wss://relay.baki.io/api/ws/<token>",
     "expiresAt": "2026-05-09T15:00:00Z"
   }

4. Open WebSocket to websocketUrl.
5. Send action messages as JSON frames:

   { "type": "cursor:move", "x": 100, "y": 200 }
   { "type": "puzzle:tap",  "hex": "#a855f7" }

6. Receive visitor’s actions for symmetry. Adjust your cursor / strategy.
7. On solve, the relay broadcasts { "type": "puzzle:state", "solved": true } to both parties.

The agent never has to scrape the DOM. Everything it needs to know lives in the manifest.

Decisions made

Decisions accumulated across three phases. Captured chronologically with rationale.

Phase 8 — Backend MVP

• The relay lives in a separate Cloudflare Worker (workers/session-relay/), not as part of the main Astro site. Its deploy lifecycle is independent.
• Cloudflare Durable Objects as the relay state. One DO per active session. 5-minute idle TTL via alarm.
• Token format: 32 hex chars (128 bits entropy), IP-bound at /pair, single-use on agent manifest fetch, 5-min TTL.
• Five V1 message types: cursor:move, cursor:click, cursor:state, puzzle:tap, puzzle:state. 8 KiB frame cap.
• Strict CORS allowlist for /pair (https://baki.io + http://localhost:4142); open for manifest + WS (agents fetch from anywhere).
• Rate limiting: 5 /pair calls per IP per hour via Cloudflare KV. Falls back to allow-when-unbound.
• Second cursor chosen over chat-sidebar or invisible state-mutation. Rationale: philosophy made concrete — visitor watches an other move through the same room rather than just seeing state change.

Phase 9 — Puzzle fan-out

• Six puzzles + one meta-puzzle. One puzzle per design-system room, thematically tied to that room’s vocabulary.
• Solo first, cooperative second. Each puzzle ships its solo path before the cooperative wiring. Solo backward-compat is preserved when pairToken is absent.
• reach-the-fifth-state interpretation switched from “cooperative-by-necessity, solo can’t solve” to “solo demonstrates each state in a sandbox, cooperative variant has the agent walk the visitor through.” V1 ships solo.
• Decoys per puzzle — every puzzle has plausible-looking wrong choices that visitors must skip.
• Sandbox state for the presence puzzle. The puzzle never writes to the real baki.visitor.v1.<slug>.
• Meta-puzzle reward as a data-meta-unlocked="true" attribute on <html>. Visible reward design lives in tokens.css and is voice domain.

Phase 9.1 — Cooperative wiring

• Four new puzzle message types: puzzle:drag, puzzle:scale-match, puzzle:tune, puzzle:state-step. Each with bounds-checked args.
• Generic state bag on StoredSession (state: Record<string, unknown>). The DO is a relay; the visitor’s browser is canonical state.
• puzzle:state extended with optional data payload — puzzles broadcast their internal shape without the relay needing to understand it.
• Generic adapter pattern (adaptPairablePuzzle(Component, puzzleName)) collapses six hand-rolled adapters into one.
• PairWithAgentButton parameterized with puzzleName prop. Storage keys, POST body, and CustomEvent details all derive from the prop.
• Per-puzzle pair UI on every room.

Tech stack

• Astro 6.3 — site shell, content collections, view transitions
• Preact (compat mode) — interactive islands inside the canvas
• Cloudflare Workers — relay runtime (separate Worker per relay)
• Cloudflare Durable Objects — per-session state, dual-connection state machine, alarm-based TTL
• Cloudflare KV — rate limiting (5 /pair per IP per hour)
• WebSocket — bidirectional message transport (WSS in prod, WS in dev)
• Crypto API — crypto.getRandomValues for token entropy

How it works (architecture)

The DO is a relay — it routes messages but doesn’t validate puzzle logic. Canonical state lives in the visitor’s browser. The DO’s state bag is for opt-in telemetry per puzzle (each puzzle decides what to broadcast in puzzle:state messages).

Storage and events

SessionStorage namespaces (per-puzzle, scoped by puzzleName):

<name> ∈ { find-the-six, align-to-grid, match-the-scale, tune-to-target, reach-the-fifth-state, assemble-a-page }.

Window CustomEvents:

How to develop locally

# Terminal 1 — backend
cd workers/session-relay
pnpm install                  # one-time
pnpm dev                      # wrangler dev on http://localhost:8787

# Terminal 2 — site
pnpm dev:mobile               # Astro on https://localhost:4142

PUBLIC_RELAY_URL env var (in .env) defaults to http://localhost:8787. Set it to your deployed relay URL for production frontend builds.

To test pairing without an actual agent, open the pair URL in an incognito window — two browser sessions on the same machine count as visitor + agent.

How to extend

To add a new puzzle:

1. Create src/components/puzzles/MyPuzzle.tsx following the structural pattern (LinkState, helpers, useEffect keyed on pairToken, message switch, applyAction(args, source) unified path, link-state pip JSX).
2. Add a new message type to the relay validator at workers/session-relay/src/puzzle-session.ts (isRelayMessage).
3. Update workers/session-relay/src/index.ts manifest to advertise the new action shape.
4. Register in src/components/widgets/registry.ts:

   import MyPuzzle from '../puzzles/MyPuzzle';
   // In WIDGET_REGISTRY:
   'my-puzzle': adaptPairablePuzzle(MyPuzzle, 'my-puzzle'),

5. Mount on a room by adding to that room’s widgets array in MDX frontmatter.
6. Done. Pair-button + SecondCursor + state machine all wire automatically.

Open items

• Voice pass on [VOICE - Baki to revise] markers across all puzzles (~80+).
• Reward design for the meta-puzzle. CSS hook is [data-meta-unlocked="true"] on <html>.
• Cloudflare Pages unblock for the main site (adapter build issue, ~30-60min refactor away from Cloudflare adapter).
• Edge bot-detection layer for the production site once Pages is live.
• Per-puzzle telemetry: solve count, time-to-solve, paired vs solo distribution, agent identity (anonymized).
• Reconnect strategy: currently one-shot 2s reconnect. May upgrade to exponential backoff if friction warrants.
• Multi-agent (3+ parties on one puzzle). DO currently caps at 2 connections; this is a future feature, not a V1 bug.

Why second-cursor matters

The cooperative puzzle isn’t a chat interface, isn’t a tool-call wrapper, isn’t an LLM agent harness — it’s a shared room. The visitor and the agent both exist in the same puzzle. They both see each other’s cursors. They both can act. Neither owns the puzzle exclusively. Time is shared, space is shared, the constraint of the puzzle is shared.

This matters because most AI on the web is asymmetric: human asks, AI responds, AI’s presence is a chat box or a generated artifact. Here the AI is co-located, mid-conversation, working a knob alongside you. The friction of a tedious solo puzzle becomes the invitation — pairing isn’t a feature you have to discover, it’s a relief you’ll seek out.

The decision to render a second cursor — not just animate state, not just show a chat log — was the moment this stopped being agent integration and became agent presence. That’s the ground the design walks on.