Live Rooms V1 + Agent Direct-Client

.github/workflows/deploy.yml

@@ -8,6 +8,7 @@ on:
       - 'apps/marketing/**'
       - 'apps/portal/**'
       - 'apps/paste-service/**'
+      - 'apps/room-service/**'
       - 'packages/**'
   workflow_dispatch:
     inputs:
@@ -21,6 +22,7 @@ on:
           - marketing
           - portal
           - paste
+          - room
 
 permissions:
   id-token: write
@@ -33,6 +35,7 @@ jobs:
       marketing: ${{ steps.changes.outputs.marketing }}
       portal: ${{ steps.changes.outputs.portal }}
       paste: ${{ steps.changes.outputs.paste }}
+      room: ${{ steps.changes.outputs.room }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
@@ -55,13 +58,19 @@ jobs:
             else
               echo "paste=false" >> $GITHUB_OUTPUT
             fi
+            if [[ "${{ inputs.target }}" == "all" || "${{ inputs.target }}" == "room" ]]; then
+              echo "room=true" >> $GITHUB_OUTPUT
+            else
+              echo "room=false" >> $GITHUB_OUTPUT
+            fi
           else
             # For push events, check what changed
             git fetch origin ${{ github.event.before }} --depth=1 2>/dev/null || true
 
             MARKETING_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/marketing/|packages/)' || true)
             PORTAL_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/portal/|packages/)' || true)
             PASTE_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^apps/paste-service/' || true)
+            ROOM_CHANGED=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} 2>/dev/null | grep -E '^(apps/room-service/|packages/shared/collab/|packages/editor/|packages/ui/)' || true)
 
             if [[ -n "$MARKETING_CHANGED" ]]; then
               echo "marketing=true" >> $GITHUB_OUTPUT
@@ -80,6 +89,12 @@ jobs:
             else
               echo "paste=false" >> $GITHUB_OUTPUT
             fi
+
+            if [[ -n "$ROOM_CHANGED" ]]; then
+              echo "room=true" >> $GITHUB_OUTPUT
+            else
+              echo "room=false" >> $GITHUB_OUTPUT
+            fi
           fi
 
   deploy-marketing:
@@ -171,3 +186,28 @@ jobs:
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+  deploy-room:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.room == 'true'
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build browser shell
+        run: bun run --cwd apps/room-service build:shell
+
+      - name: Deploy to Cloudflare
+        working-directory: apps/room-service
+        run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

.github/workflows/release.yml

@@ -41,7 +41,9 @@ jobs:
         run: bun run typecheck
 
       - name: Run tests
-        run: bun test
+        # See .github/workflows/test.yml for why this is `bun run test`
+        # and not raw `bun test`.
+        run: bun run test
 
   build:
     needs: test

.github/workflows/test.yml

@@ -29,7 +29,12 @@ jobs:
         run: bun run typecheck
 
       - name: Run tests
-        run: bun test
+        # Use the root `test` script (splits non-UI + UI-cwd) so the
+        # packages/ui/bunfig.toml happy-dom preload is loaded. Raw
+        # `bun test` from the repo root doesn't pick up that package-
+        # scoped preload, so UI hook tests would hit "document is not
+        # defined".
+        run: bun run test
 
   install-cmd-windows:
     # End-to-end integration test for scripts/install.cmd on real cmd.exe.

.gitignore

@@ -50,3 +50,17 @@ opencode.json
 plannotator-local
 # Local research/reference docs (not for repo)
 /reference/
+
+# Cloudflare Wrangler local state (Miniflare SQLite, caches)
+.wrangler/
+
+# Room-service Vite build output (chunked editor bundle served by
+# Cloudflare's [assets] binding; regenerated by `bun run build:shell`).
+apps/room-service/public/
+
+# Claude Code local scratch files (per-session locks, etc.). Intentionally
+# ignored so they can't be committed accidentally.
+.claude/scheduled_tasks.lock
+
+# Internal design/spec docs — kept locally, not shipped in PRs.
+specs/

AGENTS.md

@@ -28,6 +28,16 @@ plannotator/
 │   │   ├── index.html
 │   │   ├── index.tsx
 │   │   └── vite.config.ts
+│   ├── room-service/             # Live collaboration rooms (Cloudflare Worker + Durable Object)
+│   │   ├── core/                 # Handler, DO class, validation, CORS, log, types, csp
+│   │   ├── targets/cloudflare.ts # Worker entry + DO re-export
+│   │   ├── entry.tsx             # Browser shell entry — mounts AppRoot for /c/:roomId
+│   │   ├── index.html            # Vite template; produces hashed chunks under /assets/
+│   │   ├── vite.config.ts        # Browser shell build (bun run build:shell)
+│   │   ├── tsconfig.browser.json # DOM-lib tsconfig for the shell
+│   │   ├── static/               # Root-level static assets copied into public/ by build:shell (favicon.svg)
+│   │   ├── scripts/smoke.ts      # Integration test against wrangler dev
+│   │   └── wrangler.toml         # SQLite-backed DO binding + ASSETS binding for built shell
 │   └── vscode-extension/         # VS Code extension — opens plans in editor tabs
 │       ├── bin/                   # Router scripts (open-in-vscode, xdg-open)
 │       ├── src/                   # extension.ts, cookie-proxy.ts, ipc-server.ts, panel-manager.ts, editor-annotations.ts, vscode-theme.ts
@@ -51,16 +61,33 @@ plannotator/
 │   │   ├── components/           # Viewer, Toolbar, Settings, etc.
 │   │   │   ├── icons/            # Shared SVG icon components (themeIcons, etc.)
 │   │   │   ├── plan-diff/        # PlanDiffBadge, PlanDiffViewer, clean/raw diff views
-│   │   │   └── sidebar/          # SidebarContainer, SidebarTabs, VersionBrowser, ArchiveBrowser
-│   │   ├── utils/                # parser.ts, sharing.ts, storage.ts, planSave.ts, agentSwitch.ts, planDiffEngine.ts, planAgentInstructions.ts
-│   │   ├── hooks/                # useAnnotationHighlighter.ts, useSharing.ts, usePlanDiff.ts, useSidebar.ts, useLinkedDoc.ts, useAnnotationDraft.ts, useCodeAnnotationDraft.ts, useArchive.ts
+│   │   │   ├── sidebar/          # SidebarContainer, SidebarTabs, VersionBrowser, ArchiveBrowser
+│   │   │   └── collab/           # RoomStatusBadge, ParticipantAvatars, RoomHeaderControls, RoomMenu, RoomUnavailableScreen, JoinRoomGate, StartRoomModal, RemoteCursorLayer, ImageStripNotice
+│   │   ├── utils/                # parser.ts, sharing.ts, storage.ts, planSave.ts, agentSwitch.ts, planDiffEngine.ts, planAgentInstructions.ts, adminSecretStorage.ts, blockTargeting.ts
+│   │   ├── hooks/                # useAnnotationHighlighter.ts, useSharing.ts, usePlanDiff.ts, useSidebar.ts, useLinkedDoc.ts, useAnnotationDraft.ts, useCodeAnnotationDraft.ts, useArchive.ts, useCollabRoom.ts, useCollabRoomSession.ts, useAnnotationController.ts, useRoomMode.ts, usePresenceThrottle.ts
 │   │   └── types.ts
 │   ├── ai/                       # Provider-agnostic AI backbone (providers, sessions, endpoints)
 │   ├── shared/                   # Shared types, utilities, and cross-runtime logic
 │   │   ├── storage.ts            # Plan saving, version history, archive listing (node:fs only)
 │   │   ├── draft.ts              # Annotation draft persistence (node:fs only)
-│   │   └── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
-│   ├── editor/                   # Plan review App.tsx
+│   │   ├── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
+│   │   └── collab/               # Live Rooms protocol, crypto, validators, client runtime, React hook
+│   │       ├── types.ts          # Protocol types + runtime validators (isRoomAnnotation, isRoomSnapshot, isPresenceState, ...)
+│   │       ├── crypto.ts         # HKDF key derivation, HMAC proofs, AES-GCM payload encrypt/decrypt
+│   │       ├── ids.ts            # roomId/secret/opId/clientId generators
+│   │       ├── url.ts            # parseRoomUrl / buildRoomJoinUrl / buildAdminRoomUrl (client-only)
+│   │       ├── constants.ts      # ROOM_SECRET_LENGTH_BYTES, ADMIN_SECRET_LENGTH_BYTES, WS_CLOSE_ROOM_UNAVAILABLE, WS_CLOSE_REASON_ROOM_UNAVAILABLE
+│   │       ├── canonical-json.ts # canonicalJson for admin command proof binding
+│   │       ├── encoding.ts       # base64url helpers
+│   │       ├── strip-images.ts   # toRoomAnnotation, stripRoomAnnotationImages (image stripping for room snapshots)
+│   │       ├── redact-url.ts    # redactRoomSecrets (scrub #key=/#admin= from telemetry/logs)
+│   │       ├── validation.ts     # isBase64Url32ByteString / isValidPermissionMode
+│   │       ├── client.ts         # Client barrel re-exports
+│   │       └── client-runtime/   # CollabRoomClient class, createRoom, joinRoom, apply-event reducer
+│   ├── editor/                   # Plan review app (App.tsx) + room-mode shell
+│   │   ├── App.tsx               # Plan review editor (local + room-mode prop)
+│   │   ├── AppRoot.tsx           # Mode fork (local | room | invalid-room); package default export
+│   │   └── RoomApp.tsx           # Room-mode shell — identity gate, session, overlays, delete/expired fallbacks
 │   └── review-editor/            # Code review UI
 │       ├── App.tsx               # Main review app
 │       ├── components/           # DiffViewer, FileTree, ReviewSidebar
@@ -193,6 +220,17 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
 
 ### Plan Server (`packages/server/index.ts`)
 
+Live Rooms V1 does NOT support approve/deny from the room origin.
+Approvals always happen on the local editor origin (the tab that
+started the hook). Room-side annotations flow back to the local
+editor via the existing import paths (static share hash, paste short
+URL, "Copy consolidated feedback" → paste).
+
+Local external annotations (`/api/external-annotations` + SSE) remain
+local to the localhost editor in the current room integration.
+Forwarding those annotations into encrypted room ops is later Slice 6
+work; it is not part of the room-origin approve/deny surface.
+
 | Endpoint              | Method | Purpose                                    |
 | --------------------- | ------ | ------------------------------------------ |
 | `/api/plan`           | GET    | Returns `{ plan, origin, previousPlan, versionInfo }` (plan mode) or `{ plan, origin, mode: "archive", archivePlans }` (archive mode) |
@@ -278,6 +316,19 @@ All servers use random ports locally or fixed port (`19432`) in remote mode.
 
 Runs as a separate service on port `19433` (self-hosted) or as a Cloudflare Worker (hosted).
 
+### Room Service (`apps/room-service/`)
+
+Live-collaboration rooms for encrypted multi-user annotation. Zero-knowledge: the Worker + Durable Object stores and relays ciphertext only. Clients hold the room secret in the URL fragment and derive `authKey`/`eventKey`/`presenceKey`/`adminKey` locally.
+
+| Endpoint              | Method | Purpose                                    |
+| --------------------- | ------ | ------------------------------------------ |
+| `/health`             | GET    | Worker liveness probe                      |
+| `/c/:roomId`          | GET    | Room SPA shell — serves the built editor bundle (hashed chunks under `/assets/`). Response carries `ROOM_CSP`, `Cache-Control: no-store` on the HTML, `Referrer-Policy: no-referrer`. `:roomId` is validated against `isRoomId()` before the asset fetch. |
+| `/api/rooms`          | POST   | Create room. Body: `{ roomId, roomVerifier, adminVerifier, initialSnapshotCiphertext, expiresInDays? }`. Returns `201` on success; `409` on duplicate `roomId`. Response body is intentionally not consumed by `createRoom()`. |
+| `/ws/:roomId`         | GET    | WebSocket upgrade into the room Durable Object. `roomId` is validated via `isRoomId()` before `idFromName()` to prevent arbitrary DO instantiation. |
+
+Protocol contract lives in `packages/shared/collab/`; the Worker/DO never imports client-only URL helpers.
+
 ## Plan Version History
 
 Every plan is automatically saved to `~/.plannotator/history/{project}/{slug}/` on arrival, before the user sees the UI. Versions are numbered sequentially (`001.md`, `002.md`, etc.). The slug is derived from the plan's first `# Heading` + today's date via `generateSlug()`, scoped by project name (git repo or cwd). Same heading on the same day = same slug = same plan being iterated on. Identical resubmissions are deduplicated (no new file if content matches the latest version).