@jlongo78/agent-spaces 0.7.6 → 0.8.0

package/.next/standalone/docs/superpowers/specs/2026-03-19-vr-phase1-shell-design.md

@@ -0,0 +1,288 @@
+# Spaces VR — Phase 1: VR Shell + Static Rooms
+
+> Phase 1 of 5. Builds the spatial environment on Quest 3 using Unity + Meta XR SDK. Fetches workspace data from the Spaces server to populate the lobby. No live terminal data yet — that's Phase 2+3.
+
+---
+
+## Decisions
+
+- **Platform**: Meta Quest 3, native Unity app (not WebXR)
+- **Engine**: Unity 2022 LTS + Meta XR SDK (v68+) + Meta Interaction SDK
+- **Interaction**: Eye tracking (gaze focus) + hand tracking (grab/move/resize). No controllers.
+- **Server communication**: HTTP REST calls to existing Spaces API (WebSocket comes in Phase 2)
+- **Scope**: Lobby + workspace rooms + pane placeholders. No live data, no voice.
+
+---
+
+## 1. Unity Project Structure
+
+```
+spaces-vr/
+├── Assets/
+│   ├── Scenes/
+│   │   ├── Lobby.unity          # Central hub with workspace doors
+│   │   └── WorkspaceRoom.unity  # Template room, instantiated per workspace
+│   ├── Scripts/
+│   │   ├── Core/
+│   │   │   ├── SpacesConnection.cs    # HTTP client to Spaces API
+│   │   │   ├── SessionManager.cs      # Auth token management
+│   │   │   └── WorkspaceData.cs       # Data models (workspace, pane metadata)
+│   │   ├── Lobby/
+│   │   │   ├── LobbyManager.cs        # Spawn doors from workspace list
+│   │   │   ├── WorkspaceDoor.cs       # Individual door behavior + preview
+│   │   │   └── DoorInteraction.cs     # Gaze-select + confirm to enter
+│   │   ├── Room/
+│   │   │   ├── RoomManager.cs         # Arrange panes in semicircle, scale room
+│   │   │   ├── PaneSurface.cs         # Pane placeholder (floating surface)
+│   │   │   ├── PaneLayout.cs          # Semicircle positioning math
+│   │   │   └── PaneInteraction.cs     # Grab, move, resize via hand tracking
+│   │   ├── Interaction/
+│   │   │   ├── GazeManager.cs         # Eye tracking → focused object
+│   │   │   ├── GazeFocusHighlight.cs  # Visual feedback on gazed pane
+│   │   │   ├── HandGrabHandler.cs     # Pinch-grab for pane manipulation
+│   │   │   └── PalmMenu.cs            # Look-at-palm → home button
+│   │   └── UI/
+│   │       ├── PaneHeader.cs          # Agent name/type label on pane
+│   │       └── StatusIndicator.cs     # Glow/color for pane state
+│   ├── Prefabs/
+│   │   ├── WorkspaceDoor.prefab
+│   │   ├── PaneSurface.prefab
+│   │   └── PalmMenu.prefab
+│   ├── Materials/
+│   │   ├── PaneSurface.mat       # Dark terminal-style surface
+│   │   ├── PaneHighlight.mat     # Gaze-focus highlight shader
+│   │   └── DoorFrame.mat         # Workspace door styling
+│   └── Shaders/
+│       └── TerminalSurface.shader  # SDF text rendering on pane surfaces
+├── Packages/
+│   └── manifest.json            # Meta XR SDK, Interaction SDK, TextMeshPro
+├── ProjectSettings/
+│   └── ...                      # Quest 3 build settings, eye/hand tracking permissions
+└── README.md
+```
+
+---
+
+## 2. Lobby
+
+### Layout
+A central circular or octagonal room. The user spawns at the center. Workspace doors are arranged around the perimeter, evenly spaced.
+
+### Door Rendering
+Each door is a prefab containing:
+- **Frame** — archway or panel frame, tinted with the workspace's color (from Spaces API)
+- **Label** — workspace name as TextMeshPro above the door
+- **Preview panel** — small info card showing: pane count, active agent count, status color (green/amber/red)
+- **Glow** — subtle ambient glow in the workspace color
+
+### Data Fetching
+On lobby load:
+```
+GET /api/workspaces → [{ id, name, color, paneCount, ... }]
+```
+
+`paneCount` is already returned by the workspaces endpoint (computed via JOIN). No need for a separate pane list call for lobby previews.
+
+When entering a room:
+```
+GET /api/panes?workspace_id=N → [{ id, agent_type, title, ... }]
+```
+
+**Note:** The `GET /api/panes` route currently ignores query params and returns all active panes. Phase 1 requires adding `workspace_id` filter support to this route (small server-side change).
+
+### Auth
+Session cookie from `POST /api/auth/login` (when `@spaces/teams` is installed). Unity's `UnityWebRequest` supports cookies. If auth is not configured (Community tier, no login), the API is unauthenticated — `SpacesConnection.cs` should detect this and skip login.
+
+### Server Unreachable State
+If the server is unreachable on launch or during polling, the lobby shows a single "Offline" panel at center with the server URL and a "Retry" gaze-button. No doors rendered until connection succeeds.
+
+### Entering a Room
+- Gaze at a door for 1.5 seconds → confirmation ring fills around crosshair
+- On confirm → fade to black (0.5s) → load workspace room → fade in (0.5s)
+- Alternative: walk physically toward the door (proximity trigger at 1m)
+
+---
+
+## 3. Workspace Room
+
+### Pane Arrangement
+Panes are arranged in a semicircle at 2m radius from room center, at standing eye height (~1.6m). Arrangement adapts to pane count:
+
+| Panes | Arc | Spacing |
+|-------|-----|---------|
+| 1 | Directly ahead | — |
+| 2 | ±20° from center | 40° apart |
+| 3-4 | ±40° arc | Even spacing |
+| 5-6 | ±60° arc | Even spacing |
+| 7-8 | ±80° arc | Even spacing |
+
+Panes angle inward to face the user (billboarded on the Y axis only — they tilt toward center, not toward the user's head).
+
+### Room Scaling
+The room environment subtly scales with pane count:
+- 1-2 panes: small office feel, warm lighting
+- 3-5 panes: standard room
+- 6-8 panes: larger space, cooler lighting, slight command-center vibe
+
+### Pane Placeholder Surface
+Each pane is a floating quad (default 1.2m wide × 0.8m tall, ~16:10 ratio). In Phase 1, it shows:
+- Dark background (matching Spaces terminal theme: `#0a0a0f`)
+- Pane header bar: agent name, agent type icon, workspace color accent
+- Placeholder text: "Connecting..." or agent type name
+- Status indicator: colored dot (green=active, gray=idle, amber=waiting, red=error)
+
+### Returning to Lobby
+- Look at open palm → palm menu appears (small floating UI near hand)
+- Gaze at "Home" icon for 1s → fade transition back to lobby
+- Voice shortcut: say "go home" (Phase 4 — do not wire in Phase 1)
+
+---
+
+## 4. Eye Tracking (Gaze)
+
+### Setup
+- Enable `Eye Tracking` in OVRManager
+- Request runtime eye tracking permission (Quest 3 requires user consent)
+- Use `OVREyeGaze` component to get gaze ray
+- Raycast from gaze origin in gaze direction each frame
+- **Fallback**: if user denies eye tracking permission, fall back to head-gaze (raycast from `OVRCameraRig.centerEyeAnchor.forward`). All interaction works the same, just less precise.
+
+### Focus System
+- When gaze ray hits a `PaneSurface` collider, that pane becomes "focused"
+- Focus requires 300ms of sustained gaze (prevents flicker from glancing)
+- On focus: pane border brightens, slight scale-up (1.02x), subtle audio tick
+- On unfocus: reverse the highlight over 200ms
+- Only one pane can be focused at a time
+- When no pane is focused after 2s, a subtle "resting" state — all panes equally dim
+
+### Gaze Cursor
+- No visible crosshair/reticle in normal use (breaks immersion)
+- During door selection or palm menu: a thin ring appears as the confirmation timer
+
+---
+
+## 5. Hand Tracking
+
+### Grab to Move
+- Pinch (thumb + index) while hand overlaps pane collider → grab
+- While grabbed: pane follows hand position (with smoothing, 10ms lerp)
+- Release pinch → pane stays at new position
+- Constraint: panes stay between 1m and 4m from room center, and between 0.5m and 3m height
+
+### Pinch to Resize
+- Two-hand pinch: grab corners/edges with both hands
+- Pull apart → scale up, push together → scale down
+- Minimum size: 0.6m × 0.4m, Maximum: 2.4m × 1.6m
+- Aspect ratio preserved during resize
+
+### Scroll (Optional stretch — needed in Phase 3)
+- Pinch and drag vertically near a pane surface (not grabbing the pane itself) → scroll
+- If time permits, wire the gesture handler with a no-op callback. Otherwise defer entirely.
+
+---
+
+## 6. Server Communication (Phase 1 Scope)
+
+Phase 1 uses **HTTP only** — just enough to populate the lobby and rooms.
+
+### SpacesConnection.cs
+```csharp
+// Configurable server URL (default: http://localhost:3457)
+// Auth: POST /api/auth/login → session token stored in SessionManager
+// Workspace list: GET /api/workspaces → WorkspaceData[]
+// Pane list: GET /api/panes?workspace_id=N → PaneData[]
+// Polling: refresh workspace list every 30s while in lobby
+//          refresh pane list every 10s while in a room
+```
+
+### Data Models
+```csharp
+[Serializable]
+public class WorkspaceData {
+    public int id;
+    public string name;
+    public string color;
+    public int paneCount;    // from GET /api/workspaces (already computed server-side)
+}
+
+[Serializable]
+public class PaneData {
+    public string id;
+    public string agentType;  // "claude", "codex", "shell", etc.
+    public string title;
+}
+```
+
+**Note on pane status:** The DB has no `status` column. For Phase 1, all pane placeholders show as "idle" (gray dot). Phase 2's WebSocket connection will provide real-time status updates. The `StatusIndicator` component should accept a status enum but default to idle for now.
+
+---
+
+## 7. Performance Budget
+
+Target: 90fps (11.1ms frame time), 5ms GPU budget on Quest 3 (Adreno 740).
+
+| Scene | Triangle Budget | Draw Calls | Texture Memory |
+|-------|----------------|------------|----------------|
+| Lobby (8 doors) | 50K | 20 | 64MB |
+| Room (8 panes) | 100K | 30 | 128MB |
+
+- Pane surfaces: simple quads with SDF text shader. No post-processing.
+- Fixed foveated rendering: High (reduces peripheral pixel count by ~50%)
+- Room geometry: low-poly, baked lighting, no real-time shadows
+- TextMeshPro: SDF font atlas, single material per font size
+
+### HTTP Polling & Error Handling
+- Lobby polls workspace list every 30s. Room polls pane list every 10s.
+- Timeout: 5s per request. On timeout: skip this poll cycle, retry next interval.
+- 3 consecutive failures: show "Connection Lost" overlay, switch to 60s retry interval.
+- On reconnect: refresh all data immediately, resume normal polling.
+- Auth token expiry: re-attempt login once, show "Session Expired" if login fails.
+
+---
+
+## 8. Build & Test
+
+### Development Without Headset
+- **Meta XR Simulator** in Unity Editor: simulates eye tracking, hand tracking, room-scale movement
+- Keyboard shortcuts: WASD move, mouse look, click to simulate gaze confirm
+- All pane interaction testable in editor play mode
+
+### Quest 3 Build Settings
+- Target: Android (ARM64)
+- Graphics API: Vulkan
+- Min SDK: Android 12 (API 32)
+- Enable: Eye Tracking, Hand Tracking, Passthrough (for Phase 5)
+- Refresh rate: 90Hz target, 72Hz fallback
+- Fixed foveated rendering: High (performance optimization)
+
+### Testing with Headset
+- Quest Link for live iteration (USB-C or Air Link over WiFi)
+- SideQuest for standalone APK deployment
+- Server must be reachable from Quest (same network, or port forwarded)
+
+---
+
+## 9. Out of Scope (Later Phases)
+
+- Live terminal output rendering (Phase 3)
+- WebSocket streaming (Phase 2)
+- Voice input/output (Phase 4)
+- Spatial audio (Phase 4)
+- Pane position persistence (Phase 5)
+- Passthrough/MR mode (Phase 5)
+- Attention signals (chime/glow) for panes needing input (Phase 4)
+- Room ambiance, lighting, polish (Phase 5)
+
+---
+
+## 10. Success Criteria
+
+Phase 1 is done when:
+1. You put on the Quest 3 (or run in Meta XR Simulator) and see a lobby with doors for your actual workspaces
+2. You look at a door and the confirmation ring fills — you enter the room
+3. Inside, pane placeholders are arranged in a semicircle with correct agent names/types
+4. You can grab a pane with your hand and move it to a new position
+5. You can resize a pane with two-hand pinch
+6. Looking at a pane highlights it (eye tracking focus)
+7. Palm menu returns you to the lobby
+8. It runs at 90fps on Quest 3

package/.next/standalone/docs/tiers.md

@@ -0,0 +1,104 @@
+# Spaces Product Tiers
+
+Spaces follows an **open-core** model:
+
+- **Community** is fully open source (MIT) and free.
+- **Server**, **Team**, and **Federation** require the private `@spaces/pro` package.
+
+The tier is controlled by the `NEXT_PUBLIC_TIER` environment variable, but paid tiers are gated on `@spaces/pro` being installed. If the env var is set to a paid tier but `@spaces/pro` is missing, Spaces falls back to Community with a console warning.
+
+## Tier Comparison
+
+| Feature | Community | Server | Team | Federation |
+|---------|-----------|--------|------|------------|
+| Multi-pane terminals | Yes | Yes | Yes | Yes |
+| Session browser & search | Yes | Yes | Yes | Yes |
+| Dashboard & analytics | Yes | Yes | Yes | Yes |
+| All agent types | Yes | Yes | Yes | Yes |
+| Browser access | Yes | Yes | Yes | Yes |
+| Login & TOTP auth | - | Yes | Yes | Yes |
+| Multi-user accounts | - | - | Yes | Yes |
+| Admin panel (Users) | - | - | Yes | Yes |
+| Usage analytics (admin) | - | - | Yes | Yes |
+| Network / Nodes | - | - | - | Yes |
+| Remote workspaces | - | - | - | Yes |
+| mDNS discovery | - | - | - | Yes |
+
+## Choosing a Tier
+
+### Community
+**Target:** Solo developer, local machine.
+**Tagline:** *AI agent workspaces on your machine. Open source, forever free.*
+
+Use Community when you want a local workspace in a browser. Everything runs locally, no login required. No `@spaces/pro` dependency.
+
+### Server
+**Target:** Solo developer, remote access.
+**Tagline:** *Your Spaces, anywhere. Self-hosted web access from any browser.*
+**Requires:** `@spaces/pro`
+
+Use Server when you want to access Spaces from a browser on a remote machine. Includes login authentication and TOTP but supports only a single user.
+
+### Team
+**Target:** Developer teams.
+**Tagline:** *One server, every developer. Shared workspaces with user management.*
+**Requires:** `@spaces/pro`
+
+Use Team when multiple developers share a single Spaces server. Includes multi-user accounts, an admin panel, and usage analytics.
+
+### Federation
+**Target:** Organizations and networks.
+**Tagline:** *Connect every machine. Unified workspaces across your entire network.*
+**Requires:** `@spaces/pro`
+
+Use Federation when you need to connect multiple Spaces servers. Includes everything in Team plus network node management, remote workspace proxying, and mDNS auto-discovery.
+
+## Tier Gating Mechanism
+
+The tier system is implemented in `src/lib/tier.ts`. On startup it:
+
+1. Reads `NEXT_PUBLIC_TIER` (or the legacy `NEXT_PUBLIC_EDITION` fallback).
+2. If a `SPACES_LICENSE` JWT is present, verifies it with an Ed25519 public key (`src/lib/license.ts`).
+3. Checks whether `@spaces/pro` is installed via `src/lib/pro.ts`.
+4. If a paid tier is requested but `@spaces/pro` is not available, falls back to `community`.
+
+Feature flags exported from `tier.ts`:
+
+| Flag | Meaning |
+|------|---------|
+| `IS_SERVER` | Any tier above community |
+| `IS_TEAM` | Team or federation |
+| `IS_FEDERATION` | Federation only |
+| `HAS_AUTH` | Login is required (same as `IS_SERVER`) |
+| `HAS_MULTIUSER` | Multiple user accounts (same as `IS_TEAM`) |
+| `HAS_ADMIN` | Admin panel available (same as `IS_TEAM`) |
+| `HAS_NETWORK` | Federation networking (same as `IS_FEDERATION`) |
+| `IS_DESKTOP` | Community tier (note: name is misleading — really means "personal/local mode") |
+
+## Configuration
+
+Set the tier via environment variable:
+
+```bash
+# Desktop / browser (Community)
+NEXT_PUBLIC_TIER=community
+
+# Single-user server
+NEXT_PUBLIC_TIER=server
+
+# Multi-user team server
+NEXT_PUBLIC_TIER=team
+
+# Federated network
+NEXT_PUBLIC_TIER=federation
+```
+
+The terminal server also accepts `SPACES_TIER` for gating mDNS and proxy features:
+
+```bash
+SPACES_TIER=federation node bin/terminal-server.js
+```
+
+### Backward Compatibility
+
+If `NEXT_PUBLIC_TIER` is not set but `NEXT_PUBLIC_EDITION=server` is present, the tier defaults to `federation` (matching the previous behavior where all server features were enabled).

package/.next/standalone/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/.next/standalone/next.config.ts

@@ -0,0 +1,20 @@
+import type { NextConfig } from "next";
+
+const basePath = process.env.SPACES_BASE_PATH || '';
+
+const nextConfig: NextConfig = {
+  reactStrictMode: false,
+  output: process.env.STANDALONE === '1' ? 'standalone' : undefined,
+  basePath: basePath || undefined,
+  trailingSlash: true,
+  // Inline SPACES_BASE_PATH into the client bundle so api() can use it
+  env: { SPACES_BASE_PATH: basePath },
+  serverExternalPackages: ['better-sqlite3', 'node-pty', 'ws', 'chokidar', '@spaces/pro', '@spaces/teams', '@lancedb/lancedb'],
+  allowedDevOrigins: ['arc.robindale.com'],
+  devIndicators: false,
+  turbopack: {
+    root: process.cwd(),
+  },
+};
+
+export default nextConfig;

package/.next/standalone/nginx.conf

@@ -0,0 +1,53 @@
+worker_processes auto;
+pid /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+    sendfile on;
+
+    # Map for conditional WebSocket upgrade headers
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        ''      close;
+    }
+
+    server {
+        listen 80;
+        server_name _;
+
+        # WebSocket proxy → terminal-server on host
+        # Rewrite /spaces/ws → /ws so dev server's pathname check matches
+        location /spaces/ws {
+            proxy_pass http://host.docker.internal:3457/ws;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header Cookie $http_cookie;
+            proxy_read_timeout 86400;
+            proxy_send_timeout 86400;
+        }
+
+        # Next.js SSR + API + static assets → Next.js on host
+        # Pass through /spaces/ prefix — Next.js basePath handles it
+        # Includes WebSocket upgrade support for HMR (_next/webpack-hmr)
+        location /spaces/ {
+            proxy_pass http://host.docker.internal:3457/spaces/;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+}

package/.next/standalone/node_modules/@img/sharp-libvips-linux-x64/README.md

@@ -0,0 +1,46 @@
+# `@img/sharp-libvips-linux-x64`
+
+Prebuilt libvips and dependencies for use with sharp on Linux (glibc) x64.
+
+## Licensing
+
+This software contains third-party libraries
+used under the terms of the following licences:
+
+| Library       | Used under the terms of                                                                                   |
+|---------------|-----------------------------------------------------------------------------------------------------------|
+| aom           | BSD 2-Clause + [Alliance for Open Media Patent License 1.0](https://aomedia.org/license/patent-license/)  |
+| cairo         | Mozilla Public License 2.0                                                                                |
+| cgif          | MIT Licence                                                                                               |
+| expat         | MIT Licence                                                                                               |
+| fontconfig    | [fontconfig Licence](https://gitlab.freedesktop.org/fontconfig/fontconfig/blob/main/COPYING) (BSD-like)   |
+| freetype      | [freetype Licence](https://git.savannah.gnu.org/cgit/freetype/freetype2.git/tree/docs/FTL.TXT) (BSD-like) |
+| fribidi       | LGPLv3                                                                                                    |
+| glib          | LGPLv3                                                                                                    |
+| harfbuzz      | MIT Licence                                                                                               |
+| highway       | Apache-2.0 License, BSD 3-Clause                                                                          |
+| lcms          | MIT Licence                                                                                               |
+| libarchive    | BSD 2-Clause                                                                                              |
+| libexif       | LGPLv3                                                                                                    |
+| libffi        | MIT Licence                                                                                               |
+| libheif       | LGPLv3                                                                                                    |
+| libimagequant | [BSD 2-Clause](https://github.com/lovell/libimagequant/blob/main/COPYRIGHT)                               |
+| libnsgif      | MIT Licence                                                                                               |
+| libpng        | [libpng License](https://github.com/pnggroup/libpng/blob/master/LICENSE)                                  |
+| librsvg       | LGPLv3                                                                                                    |
+| libspng       | [BSD 2-Clause, libpng License](https://github.com/randy408/libspng/blob/master/LICENSE)                   |
+| libtiff       | [libtiff License](https://gitlab.com/libtiff/libtiff/blob/master/LICENSE.md) (BSD-like)                   |
+| libvips       | LGPLv3                                                                                                    |
+| libwebp       | New BSD License                                                                                           |
+| libxml2       | MIT Licence                                                                                               |
+| mozjpeg       | [zlib License, IJG License, BSD-3-Clause](https://github.com/mozilla/mozjpeg/blob/master/LICENSE.md)      |
+| pango         | LGPLv3                                                                                                    |
+| pixman        | MIT Licence                                                                                               |
+| proxy-libintl | LGPLv3                                                                                                    |
+| zlib-ng       | [zlib Licence](https://github.com/zlib-ng/zlib-ng/blob/develop/LICENSE.md)                                |
+
+Use of libraries under the terms of the LGPLv3 is via the
+"any later version" clause of the LGPLv2 or LGPLv2.1.
+
+Please report any errors or omissions via
+https://github.com/lovell/sharp-libvips/issues/new