# Project export: BossRoom - Gamifying Work Across 900+ Apps This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: TreeHacks 2026 - Tagline: AI Agents require configuration, not collaboration. We built coworkers. In BossRoom, step into a 3D office, talk to a team, ask anything, and watch them go: emails sent, tickets closed, real work done - Devpost: https://devpost.com/software/bossroom - GitHub: https://github.com/Viditjn02/BossRoom - Demo: https://bossroom.pages.dev/ - Video: https://www.youtube.com/embed/fjyxESEvFjY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 3 GitHub contributor(s) — ArvinH16 (165 commits), Viditjn02 (22 commits), Cursor (11 commits) ## Devpost submission (written by the team) ### Inspiration AI agents are powerful, but interaction is still tool-centric: prompts, configs, dashboards. We built an interface where delegation is spatial and direct — like walking up to a coworker and stating the outcome. What It Does BossRoom is a real-time multiplayer 3D office where AI agents are persistent coworkers. Real Execution (Not Chat) Agents execute real work across 900+ enterprise integrations : Messaging & Communication: Slack, Microsoft Teams, Discord, WhatsApp Business Email & Calendar: Gmail, Outlook, Google Calendar Docs & Knowledge: Notion, Confluence, Google Docs/Drive, Airtable Whiteboarding & Design: Miro, Figma Project & Issue Tracking: Linear, Jira, GitHub, GitLab CRM & Sales: Salesforce, HubSpot DevOps & Cloud: AWS, GCP, Azure Databases & Infra: PostgreSQL, MongoDB, Supabase Commerce & Payments: Stripe, Visa Intelligent Commerce (MCP) Search & Data: SERP APIs, live product search, external data sources All actions execute in real user-scoped accounts via secure OAuth — no API key's, no configuration. Dynamic Multi-Agent Teams A Receptionist receives a goal (e.g., “research competitors + write report”). It dynamically spawns 3–12 agents via tool calls. The LLM decides roles, skills, and leadership. A lead agent delegates subtasks to workers. Workers post updates to a shared scratchpad feed. The lead compiles and finalizes output. All agents and workspace state persist in PostgreSQL. No hardcoded bots. Every workspace builds itself from the goal. Interaction Layer Push-to-talk voice input Real-time transcription → execution → spoken response Agents have visible states (listening, thinking, working, done, error) Proximity-based player voice chat (WebRTC spatial audio) World Layer Procedurally generated chunked terrain (simplex noise, LOD) Physics-based controls Multiple avatar models In-world 3D speech bubbles + visual state indicators - In-world integrated views from your favorite apps Architecture Frontend Next.js 16 + React 19 + TypeScript + Tailwind v4 React Three Fiber + drei Rapier physics Zustand (14 stores) synced via WebSocket 46 typed WebSocket message types, validated with Zod shadcn/ui for panels, scratchpad, product cards Backend Node.js WebSocket game server (domain-driven modules) PostgreSQL 15 + Drizzle ORM (7 tables) Dynamic agent creation + runtime skill system Vercel AI SDK (streamText, multi-step tool calls) Vercel AI Gateway (Gemini / Claude / GPT-4o swappable) Composio OAuth for Gmail, Calendar, Linear, Stripe etc MCP support for external tool servers (Visa Intelligent Commerce) Voice Two independent spatial pipelines (shared AudioContext): Agent voice loop Mic → WebSocket → Deepgram (STT) LLM execution Inworld TTS → HRTF spatial playback Agent voice loop Mic → WebSocket → Deepgram (STT) LLM execution Inworld TTS → HRTF spatial playback Player voice PeerJS WebRTC HRTF panner per remote player Distance-based rolloff Player voice PeerJS WebRTC HRTF panner per remote player Distance-based rolloff Infrastructure Terraform-managed infrastructure Google Cloud Run (WebSocket server, 3600s timeout) Cloud SQL (Postgres) Cloudflare Pages (frontend) Firebase Auth (Google Sign-In) Cloud Build → Artifact Registry → Docker deploy Fully deployed. Not localhost. Challenges Building a physics-based 3D world with responsive third-person controls Real-time multiplayer state sync (positions, agent state, scratchpad, products) over a single multiplexed WebSocket connection Designing and validating 46 typed WebSocket message types (end-to-end Zod schema enforcement) Dynamic agent spawning (3–12 agents per workspace) with persistent storage and zero race conditions during streaming tool calls Multi-step LLM tool orchestration (up to 25 steps/turn) without blocking or state corruption Maintaining per-agent memory, role separation, and runtime skill creation Dual spatial audio pipelines (agent TTS + WebRTC player voice) sharing one AudioContext without interference Real-time STT → LLM → TTS voice loop with spatial playback tied to 3D coordinates OAuth scoping per user across 900+ integrations (secure isolation per Firebase UID) MCP tool server integration (Visa Intelligent Commerce) with fallback payment rails Cloud Run WebSocket deployment (HTTP/1.1, 3600s timeout, SQL proxy sidecar, keepalive strategy) Streaming AI responses while preserving deterministic game-state updates Procedural chunked terrain generation with LOD and performance constraints - Shipping production infra (Terraform, Cloud Build, Docker, Cloud SQL, Cloudflare Pages) during a 36-hour hackathon Accomplishments Turned “agent workflows” into a game loop: walk up → ask → watch progress → get the outcome. Made non-technical users effective on day one — no prompt craft, no dashboards, no setup rituals. Converted messy, multi-step execution into a single clear interaction: users state intent, the system handles planning + delegation + tool actions. Made agent work observable: you can see who’s doing what and hear responses spatially, instead of guessing in a black box. Built a collaborative feel (multiplayer + proximity voice) so delegating to AI feels like working in a room, not using a tool. Shipped real-world execution end-to-end (emails, tickets, meetings, payments) inside a fully deployed product in 36 hours. ~179 commits 6,000+ lines of TypeScript 46 WebSocket message types 14 Zustand stores 7 database tables Full infrastructure-as-code deployment This is a working system, not just a prototype. What We Learned The interface layer matters as much as the model. Dynamic team creation — letting the LLM design the org structure per task — was the key architectural unlock. Coordination becomes intuitive when agents are embodied, stateful, and observable. What’s Next Automatic model routing per task type Visible in-world agent-to-agent collaboration Cross-workspace skill marketplace Expanded MCP integrations Deeper in-world commerce flows Every team will manage fleets of AI agents. BossRoom is the interface layer. ## README (from the GitHub repository) # BossRoom **A multiplayer 3D virtual office where AI agents are your coworkers.** Walk around, talk to them by voice or text, and watch them execute real work — send emails, book meetings, create tickets, search products, process payments — all live. Built in 36 hours at TreeHacks 2026. 179 commits. 6,000+ lines of TypeScript. 100M+ LLM tokens burned on our own dime. BossRoom --- ## Inspiration Using AI agents today feels like using a computer before GUIs existed. You type prompts into chat boxes, configure API keys, manage tools through dashboards. It's powerful — but it's the command line era of AI. It locks out most people and strips away any sense of collaboration or fun. We asked: **what if we built the graphical interface for AI agents?** Not another chat wrapper. Not another dashboard. A living 3D world where you walk up to an AI character — the way you'd walk up to a coworker — and just tell it what you need. It figures out the team, assigns the work, and you watch it happen. We drew inspiration from Astro Bot's CPU Plaza (spatial exploration as discovery), Papa's Pizzeria (microinteractions that make mundane tasks feel alive), and GTA's onboarding (progressive disclosure through gameplay). We wanted that same feeling — but for getting real work done with AI. The result is something we honestly didn't think was possible in 36 hours: a full game engine, a multi-agent AI orchestration system, real-time voice pipelines, a commerce platform, multiplayer networking, and production cloud infrastructure — all working together. ## What it does BossRoom is a **multiplayer 3D virtual office** where AI agents are your coworkers. You navigate a third-person character through a physics-enabled world, walk up to agents at their desks, and delegate real tasks — by typing or by holding a push-to-talk key and speaking naturally. **These agents don't just chat. They execute.** They send actual emails through Gmail, create real tickets in Linear, book real meetings on Google Calendar, search real products across retailers, and process real payments through Visa. ### The Receptionist: Dynamic Team Assembly The Receptionist is your office concierge. Describe any task — "research my company's competitors and write a report" — and it **dynamically creates an entire team of specialized AI agents on the fly**. A Research Lead, a Deep Researcher, a Report Writer, a Fact Checker — each with a unique name, personality, color, skill set, and zone in the office. The lead agent immediately starts delegating subtasks to workers. All agents post updates to a shared scratchpad feed. The entire team is persisted to a PostgreSQL database and survives server restarts. We didn't hardcode agents. The LLM decides how many agents to create (3-12), what skills they need, and who leads. Every workspace is different. ### The Shopkeeper: In-Game Commerce Walk up to the Shopkeeper and say "find me wireless headphones under $50." It searches real products via Visa Intelligent Commerce MCP, renders interactive product cards with real images, prices, and ratings — and you can click Buy to process a payment through Visa, all without leaving the 3D world. ### Voice — Both Ways, Spatialized in 3D Talk to agents using push-to-talk — your voice is transcribed in real-time by Deepgram Nova-3 via streaming WebSocket. Agents respond with synthesized voice (Inworld TTS) played through **HRTF spatial audio** — their voice gets louder as you walk closer and pans left/right based on their 3D position. Players can also voice chat with each other using **proximity-based P2P spatial audio** over WebRTC — hold T near another player and their voice fades in with distance, just like real life. Two completely independent spatial audio pipelines sharing a single AudioContext. ### The World The office sits on **procedurally generated terrain** using simplex noise with Minecraft-style quantized heights, vertex-colored grass and earth, flowers and decorations — chunk-loaded around the player with LOD falloff. Walk far enough past the office walls and you'll discover a hidden Stanford campus model surrounding the building. 13 selectable avatar models with live 3D previews. A Roblox-style third-person camera with right-click orbit and scroll zoom. Background music with a track selector. A GTA-style onboarding tutorial. Bloom and vignette post-processing. It's a game. ## How we built it This is not a simple stack. We built a **real-time game engine**, a **multi-agent AI orchestration system**, **dual spatial voice pipelines**, a **commerce platform**, and **production cloud infrastructure** — and wired them all together over WebSocket in 36 hours. ### 3D Game Engine (Frontend) React Three Fiber + drei + Rapier physics, running inside Next.js 16 with React 19, TypeScript, and Tailwind v4. We built a Roblox-style third-person camera with physics-based character controls using ecctrl. 13 Kenney.nl character models with idle/walk/sprint/jump animations. Procedurally generated chunked terrain using simplex noise with Minecraft-style quantized heights, vertex colors, LOD (near chunks at full resolution, far chunks at 8-cell), and small decorations (flowers, grass tufts). Agent visual states (idle, listening, thinking, working, done, error) are driven by 14 Zustand stores synchronized with the server over WebSocket. HTML speech bubbles positioned in 3D space above agents. Bloom and vignette post-processing make status orbs and neon strips glow. shadcn/ui components for chat panels, product cards, scratchpad feed, and workspace management. 46 distinct WebSocket message types in a fully typed protocol with Zod validation on both ends. ### Multi-Agent AI Orchestration (Backend) A Node.js WebSocket game server with a domain-driven architecture (7 modules: agents, conversations, players, scratchpad, skills, users, workspaces). The Receptionist agent dynamically creates 3-12 specialized agents per workspace using a `setup_workspace` tool — the LLM decides the team composition, skill definitions, and leadership structure. Each agent gets a compiled system prompt, its own conversation history, access to Composio OAuth tools scoped per-user, and the ability to create new skills for itself at runtime. AI calls use the **Vercel AI SDK** (`streamText` with multi-step tool calling, `stopWhen: stepCountIs(25)`) routed through **Vercel AI Gateway** — a unified proxy that lets us swap between Gemini, Claude, and GPT-4o per agent with a single API key. Real-world actions (Gmail, Calendar, Linear, Stripe, SerpAPI) flow through **Composio** OAuth integrations giving each user scoped access to their own accounts. The lead agent delegates tasks to workers via `delegate_task`, workers post to a shared scratchpad, and when the lead calls `finish_task` the Receptionist compiles a final summary from all agent outputs. We also built **MCP (Model Context Protocol)** support — the Shopkeeper connects to **Visa's Intelligent Commerce MCP server** for product search and payment processing. Any external tool server can be plugged in. ### Dual Spatial Voice Pipelines **Pipeline 1 — Agent voice (STT + TTS):** Client records mic audio, streams it over WebSocket to Deepgram Nova-3 for real-time transcription. The transcript is sent as an `agent:message`. The server generates a voice response via Inworld TTS API and sends base64 MP3 back over WebSocket. The client decodes it and plays it through an **HRTF PannerNode** positioned at the agent's 3D coordinates — the voice literally comes from where the agent is standing in the world. **Pipeline 2 — Player-to-player proximity voice (WebRTC):** PeerJS establishes P2P audio connections between nearby players. Each remote player's MediaStream is routed through its own HRTF PannerNode positioned at their real-time 3D location — voice fades naturally with d [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 203 recognized source files, 973 KB. - CSS (language) — detected in the code - Firebase (technology) — detected in the code - JavaScript (language) — detected in the code - Next.js (technology) — detected in the code - OpenAI (technology) — detected in the code - PostgreSQL (technology) — detected in the code - React (technology) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - Vercel AI SDK (technology) — detected in the code - Google Gemini (technology) — claimed on Devpost, not found in the code - Node.js (technology) — claimed on Devpost, not found in the code - AI coding agent: Claude Code — evidence: config files committed to the repository - AI coding agent: Cursor — evidence: commit authorship or trailers ## Codebase structure (from repository index) ### Files (120 of 272) ``` .claude/agents/codebase-explorer.md .claude/agents/implementation-reviewer.md .claude/agents/implementer.md .claude/agents/plan-reviewer.md .claude/agents/researcher.md .claude/commands/create-prp.md .claude/commands/fix-bug.md .claude/commands/implement-plan.md .claude/commands/linter/codebase.md .claude/commands/linter/commit.md .claude/commands/linter/local-changes.md .claude/commands/linter/update-claude-docs.md .claude/commands/linter/validate-codebase-docs.md .claude/commands/refactor/deep.md .claude/commands/refactor/medium.md .claude/commands/refactor/refactor-full.md .claude/commands/refactor/simple.md .claude/commands/review-plan.md .claude/commands/review-prp.md .claude/commands/review/all.md .claude/commands/review/principles/antipatterns.md .claude/commands/review/principles/architecture-backend.md .claude/commands/review/principles/architecture-frontend.md .claude/commands/review/principles/circular-deps.md .claude/commands/review/principles/clarity.md .claude/commands/review/principles/documentation.md .claude/commands/review/principles/reuse.md .claude/commands/review/principles/scope.md .claude/commands/review/principles/self-contained.md .claude/commands/review/principles/single-pattern.md .claude/commands/review/principles/tanstack-query.md .claude/commands/simple-plan.md .claude/settings.json .claude/skills/discussion/SKILL.md .claude/skills/implement/SKILL.md .claude/skills/investigate-bug/SKILL.md .claude/skills/plan/plan_base.md .claude/skills/plan/SKILL.md .claude/skills/prepare-pr/SKILL.md .claude/skills/research-web/SKILL.md .claude/skills/simple-plan/SKILL.md .dockerignore .env.example .gitattributes .github/workflows/deploy-server.yml .gitignore .nxignore .vscode/extensions.json .vscode/launch.json add-visa-credentials.sh apps/game-frontend/.swcrc apps/game-frontend/components.json apps/game-frontend/index.d.ts apps/game-frontend/next.config.js apps/game-frontend/package.json apps/game-frontend/postcss.config.mjs apps/game-frontend/project.json apps/game-frontend/public/.gitkeep apps/game-frontend/public/models/.gitkeep apps/game-frontend/public/models/characters/agent-clockwork.glb apps/game-frontend/public/models/characters/agent-mailbot.glb apps/game-frontend/public/models/characters/agent-taskmaster.glb apps/game-frontend/public/models/characters/avatars/character-female-a.glb apps/game-frontend/public/models/characters/avatars/character-female-b.glb apps/game-frontend/public/models/characters/avatars/character-female-c.glb apps/game-frontend/public/models/characters/avatars/character-female-d.glb apps/game-frontend/public/models/characters/avatars/character-female-e.glb apps/game-frontend/public/models/characters/avatars/character-female-f.glb apps/game-frontend/public/models/characters/avatars/character-male-a.glb apps/game-frontend/public/models/characters/avatars/character-male-b.glb apps/game-frontend/public/models/characters/avatars/character-male-c.glb apps/game-frontend/public/models/characters/avatars/character-male-d.glb apps/game-frontend/public/models/characters/avatars/character-male-e.glb apps/game-frontend/public/models/characters/avatars/character-male-f.glb apps/game-frontend/public/models/characters/player.glb apps/game-frontend/public/models/furniture/bookcaseOpen.glb apps/game-frontend/public/models/furniture/chairDesk.glb apps/game-frontend/public/models/furniture/computerKeyboard.glb apps/game-frontend/public/models/furniture/computerMouse.glb apps/game-frontend/public/models/furniture/computerScreen.glb apps/game-frontend/public/models/furniture/desk.glb apps/game-frontend/public/models/furniture/deskCorner.glb apps/game-frontend/public/models/furniture/lampSquareFloor.glb apps/game-frontend/public/models/furniture/laptop.glb apps/game-frontend/public/models/furniture/loungeSofa.glb apps/game-frontend/public/models/furniture/pottedPlant.glb apps/game-frontend/public/models/furniture/tableCoffee.glb apps/game-frontend/public/models/furniture/trashcan.glb apps/game-frontend/public/models/stanford-campus.glb apps/game-frontend/README.md apps/game-frontend/src/app/get-query-client.ts apps/game-frontend/src/app/global.css apps/game-frontend/src/app/layout.tsx apps/game-frontend/src/app/page.module.css apps/game-frontend/src/app/page.tsx apps/game-frontend/src/app/providers.tsx apps/game-frontend/src/app/test-chat/page.tsx apps/game-frontend/src/components/auth/LoginPage.tsx apps/game-frontend/src/components/game/Agent.tsx apps/game-frontend/src/components/game/CameraRig.tsx apps/game-frontend/src/components/game/CharacterModel.tsx apps/game-frontend/src/components/game/EmbedScreen.tsx apps/game-frontend/src/components/game/Game.tsx apps/game-frontend/src/components/game/InteractionPrompt.tsx apps/game-frontend/src/components/game/MissionControlSky.tsx apps/game-frontend/src/components/game/Office.tsx apps/game-frontend/src/components/game/Player.tsx apps/game-frontend/src/components/game/PunchHint.tsx apps/game-frontend/src/components/game/RemotePlayer.tsx apps/game-frontend/src/components/game/Scene.tsx apps/game-frontend/src/components/game/SpatialAudioListener.tsx apps/game-frontend/src/components/game/SpeechBubble.tsx apps/game-frontend/src/components/game/StanfordCampus.tsx apps/game-frontend/src/components/game/Terrain.tsx apps/game-frontend/src/components/game/ThoughtBubble.tsx apps/game-frontend/src/components/game/ViewHint.tsx apps/game-frontend/src/components/game/Workstation.tsx apps/game-frontend/src/components/ui/AgentAvatar.tsx apps/game-frontend/src/components/ui/AgentStatusBadge.tsx apps/game-frontend/src/components/ui/avatar.tsx [152 more files omitted for size] ``` ### Dependencies - apps/game-frontend/package.json: @bossroom/shared-types@*, @bossroom/shared-utils@*, @react-three/drei@^10.7.7, @react-three/fiber@^9.5.0, @react-three/postprocessing@^3.0.4, @react-three/rapier@^2.2.0, @tanstack/react-query@^5.90.21, @tanstack/react-query-devtools@^5.91.3, @types/three@^0.182.0, ecctrl@^1.0.97, next@~16.0.1, peerjs@^1.5.5, radix-ui@^1.4.3, react@^19.0.0, react-dom@^19.0.0, simplex-noise@^4.0.3, three@^0.182.0, zustand@^5.0.11 - libs/shared-types/package.json: tslib@^2.3.0, zod@* - libs/shared-utils/package.json: tslib@^2.3.0 - package.json: @ai-sdk/mcp@^1.0.21, @ai-sdk/openai@^3.0.29, @composio/core@^0.6.3, @composio/vercel@^0.6.3, @nx/esbuild@22.5.0, @nx/js@^22.5.0, @nx/next@^22.5.0, @nx/node@^22.5.0, @radix-ui/react-avatar@^1.1.11, @radix-ui/react-scroll-area@^1.2.10, @radix-ui/react-slot@^1.2.4, @swc-node/register@1.11.1, @swc/cli@~0.8.0, @swc/core@1.15.8, @swc/helpers@0.5.18, @tailwindcss/postcss@^4.1.18, @tanstack/eslint-plugin-query@^5.91.4, @types/node@20.19.9, @types/pg@^8.16.0, @types/react@^19.0.0, @types/react-dom@^19.0.0, @types/ws@^8.18.1, @visa/api-client@file:vendor/visa-mcp/packages/api-client, @visa/mcp-client@file:vendor/visa-mcp/packages/mcp-client, @visa/token-manager@file:vendor/visa-mcp/packages/token-manager, ai@^6.0.86, class-variance-authority@^0.7.1, clsx@^2.1.1, dotenv@^17.3.1, drizzle-kit@^0.31.9, drizzle-orm@^0.45.1, drizzle-zod@^0.8.3, esbuild@^0.19.2, eslint@^9.39.2, firebase@^12.9.0, firebase-admin@^13.6.1, lucide-react@^0.564.0, next@~16.0.1, nx@22.5.0, pg@^8.18.0, prettier@^2.6.2, react@^19.0.0, react-dom@^19.0.0, react-markdown@^10.1.0, remark-gfm@^4.0.1, tailwind-merge@^3.4.0, tailwindcss@^4.1.18, tslib@^2.3.0, typescript@~5.9.2, typescript-eslint@^8.55.0, ws@^8.19.0, zod@^4.3.6 ### Recent commits (newest first) - Merge branch 'main' of https://github.com/Viditjn02/BossRoom - Update README with project details and image - feat: add Visa Intelligent Commerce integration - fix: Draco-compress Stanford campus model to fit Cloudflare Pages 25 MiB limit - fix: Remove orphaned visa-mcp submodule gitlink breaking Cloudflare build - docs: Update README, Devpost, and plan for TreeHacks submission - fix: Refetch conversation history on workspace switch - Merge main into arvin: bring in workspaces, shopkeeper, avatar previews, camera toggle - adding the prds - feat: Replace TodoPanel overlay with hybrid 3D MissionControlSky board - fix: Workspace shortcuts open panel without flash, support Cmd on Mac - fix: Suppress TS error for optional @visa/mcp-client import - feat: Floating workspace bar in bottom-right with keyboard shortcuts - feat: DB-backed persistent workspaces with tab switching - feat: Change camera view toggle to V key with one-time hint - feat: Replace avatar picker emojis with live 3D character previews and personality names - feat: Add TTS audio to dynamic (sub) agents with hardcoded Dominus voice - Add Shopkeeper agent with product cards, Visa MCP, and Composio integration - fix: Block Composio auth links from embed, add team feed empty state - feat: Open chat links in embed viewer instead of new tab ## Key source files (fetched from GitHub, selected and truncated for size) ### VISA_PORTAL_GUIDE.md ```markdown # Visa Developer Portal Quick Guide You're logged in! Here's exactly what to do next: ## 🎯 Current Step: Create Your Project ### 1. Find "Add New Project" Button - Look in the top right or center of your dashboard - Click **"Add New Project"** or **"Create Project"** ### 2. Fill in Project Details ``` Project Name: BossRoom AI Agents Description: AI agent payment integration for autonomous commerce ``` ### 3. Select APIs **Required APIs:** - ✅ **Visa Intelligent Commerce** (VIC) - Primary API for agent payments - ✅ **Visa Token Service** (VTS) - Card tokenization **How to add:** - Click "Add APIs" or similar - Search for "Visa Intelligent Commerce" - Select it - Search for "Visa Token Service" - Select it ### 4. Choose Authentication Select: **XPay Token** (API Key - Shared Secret) - This is the simplest method - No complex certificate setup needed initially ### 5. Create the Project Click **"Create"** or **"Submit"** --- ## 📋 After Project Creation ### Step A: Get VIC Credentials 1. Go to your project dashboard 2. Find the **"Credentials"** tab 3. You'll see: ``` API Key: [copy this] → VISA_VIC_API_KEY Shared Secret: [copy this] → VISA_VIC_API_KEY_SS External Client ID: [copy this] → VISA_EXTERNAL_CLIENT_ID External App ID: [copy this] → VISA_EXTERNAL_APP_ID ``` ### Step B: Get VTS Credentials 1. In the same project, look for **"Visa Token Service"** section 2. Go to VTS **"Credentials"** 3. You'll see: ``` VTS API Key: [copy this] → VISA_VTS_API_KEY VTS Shared Secret: [copy this] → VISA_VTS_API_KEY_SS ``` ### Step C: Upload MLE Certificate Request 1. Find **"Encryption Keys"** or **"Security"** section 2. Look for **"Upload CSR"** or **"Certificate Signing Request"** 3. Upload the file: `visa-mle-csr.pem` (in your project root) 4. Visa will process it and provide: - **Server Certificate** (download this) - **Key ID** (note this down) --- ## 💻 Easy Credential Entry Once you have all the credentials, run this helper script: ```bash ./add-visa-credentials.sh ``` It will prompt you for each credential and automatically update your `.env` file! **Or manually update `.env`:** ```bash # Open .env and find the VISA_ section # Paste each credential next to its corresponding variable nano .env ``` --- ## 📝 Credentials Checklist Track what you've copied: **From VIC Credentials:** - [ ] `VISA_VIC_API_KEY` - [ ] `VISA_VIC_API_KEY_SS` - [ ] `VISA_EXTERNAL_CLIENT_ID` - [ ] `VISA_EXTERNAL_APP_ID` **From VTS Credentials:** - [ ] `VISA_VTS_API_KEY` - [ ] `VISA_VTS_API_KEY_SS` **From MLE/Encryption:** - [ ] Upload `visa-mle-csr.pem` - [ ] Download server certificate - [ ] Note `VISA_KEY_ID` - [ ] Add server cert to `.env` as `VISA_MLE_SERVER_CERT` --- ## 🚨 Common Issues ### "Can't find Visa Intelligent Commerce API" - Try searching for just "Intelligent Commerce" - Or look under "Beta APIs" or "New Products" - Contact Visa support if still not visible ### "No Credentials tab visible" - Make sure project creation c [truncated — 928 more characters] ``` ### VISA_CREDENTIALS_STATUS.md ```markdown # Visa Credentials Status ## ✅ Generated via CLI (Already in .env) ### 1. MLE Private Key - `VISA_MLE_PRIVATE_KEY` ✅ - **Status**: Generated and added to `.env` - **Type**: RSA 2048-bit private key - **Used for**: Message Level Encryption ### 2. JWT Signing Key - `USER_SIGNING_PRIVATE_KEY` ✅ - **Status**: Generated and added to `.env` - **Type**: RSA 2048-bit PKCS#8 private key - **Used for**: Signing JWTs before encryption ### 3. MLE Certificate Signing Request (CSR) ✅ - **Status**: Generated and saved to `visa-mle-csr.pem` - **Next Step**: Upload this to Visa Developer Portal to get the server certificate - **Location**: `./visa-mle-csr.pem` ## ❌ Must Get from Visa Developer Portal These credentials **CANNOT** be generated via CLI. You must get them from https://developer.visa.com/portal: ### 1. VIC API Credentials - [ ] `VISA_VIC_API_KEY` - From your VIC project dashboard - [ ] `VISA_VIC_API_KEY_SS` - Shared secret for VIC API ### 2. Client Identification - [ ] `VISA_EXTERNAL_CLIENT_ID` - External client identifier - [ ] `VISA_EXTERNAL_APP_ID` - External application identifier ### 3. VTS API Credentials - [ ] `VISA_VTS_API_KEY` - From your VTS project dashboard - [ ] `VISA_VTS_API_KEY_SS` - Shared secret for VTS API ### 4. MLE Server Certificate - [ ] `VISA_MLE_SERVER_CERT` - Upload `visa-mle-csr.pem` to Visa portal, download certificate - [ ] `VISA_KEY_ID` - Key identifier from Visa dashboard ## 📋 Step-by-Step: Get Visa Credentials ### Step 1: Create Visa Developer Account ```bash # Open in browser: open https://developer.visa.com/portal # Or manually visit: https://developer.visa.com/portal ``` - Sign up for an account - Verify your email ### Step 2: Create a VIC Project 1. Click "Add New Project" 2. Name: "BossRoom AI Agents" 3. Select "Visa Intelligent Commerce" 4. Choose authentication: "XPay Token" 5. Click "Create Project" ### Step 3: Get API Credentials In your project dashboard: 1. Go to "Credentials" section 2. Copy these values to `.env`: - API Key → `VISA_VIC_API_KEY` - Shared Secret → `VISA_VIC_API_KEY_SS` - External Client ID → `VISA_EXTERNAL_CLIENT_ID` - External App ID → `VISA_EXTERNAL_APP_ID` ### Step 4: Add VTS API 1. In same project, add "Visa Token Service" API 2. Get VTS credentials: - VTS API Key → `VISA_VTS_API_KEY` - VTS Shared Secret → `VISA_VTS_API_KEY_SS` ### Step 5: Upload CSR for MLE Certificate 1. In project dashboard, go to "Encryption Keys" 2. Upload the file: `visa-mle-csr.pem` 3. Download the server certificate Visa provides 4. Convert the certificate to single-line format: ```bash # Format the certificate (replace with your downloaded cert file): awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' downloaded_cert.pem ``` 5. Add to `.env`: - Formatted certificate → `VISA_MLE_SERVER_CERT` - Key ID from dashboard → `VISA_KEY_ID` ## 🔍 Quick Verification Check what's missing: ```bash # Check which credentials are empty grep "^VISA_.*=$" .env grep "^USER_SIGNING_PRIV [truncated — 1207 more characters] ``` ### package.json ``` { "name": "@org/source", "version": "0.0.0", "license": "MIT", "scripts": { "dev": "NX_TUI=false npx nx run-many -t dev -p @org/game-frontend,@org/game-server", "dev:frontend": "npx nx dev @org/game-frontend", "dev:server": "npx nx dev @org/game-server", "build": "npx nx run-many -t build", "lint": "npx eslint 'apps/**/*.{ts,tsx}' 'libs/**/*.ts' 'scripts/**/*.mjs'", "db:push": "npx drizzle-kit push --config=apps/game-server/src/db/drizzle.config.ts", "db:generate": "npx drizzle-kit generate --config=apps/game-server/src/db/drizzle.config.ts", "db:migrate": "npx drizzle-kit migrate --config=apps/game-server/src/db/drizzle.config.ts", "db:studio": "npx drizzle-kit studio --config=apps/game-server/src/db/drizzle.config.ts", "generate:env": "node scripts/generate-env.mjs", "health": "node scripts/health-check.mjs" }, "private": true, "devDependencies": { "@nx/esbuild": "22.5.0", "@nx/js": "^22.5.0", "@nx/next": "^22.5.0", "@nx/node": "^22.5.0", "@swc-node/register": "1.11.1", "@swc/cli": "~0.8.0", "@swc/core": "1.15.8", "@swc/helpers": "0.5.18", "@tanstack/eslint-plugin-query": "^5.91.4", "@types/node": "20.19.9", "@types/pg": "^8.16.0", "@types/react": "^19.0.0", "@types/react-dom": "^19.0.0", "@types/ws": "^8.18.1", "drizzle-kit": "^0.31.9", "esbuild": "^0.19.2", "eslint": "^9.39.2", "nx": "22.5.0", "prettier": "^2.6.2", "tslib": "^2.3.0", "typescript": "~5.9.2", "typescript-eslint": "^8.55.0" }, "workspaces": [ "packages/*", "apps/*", "libs/*" ], "dependencies": { "@ai-sdk/mcp": "^1.0.21", "@ai-sdk/openai": "^3.0.29", "@composio/core": "^0.6.3", "@composio/vercel": "^0.6.3", "@radix-ui/react-avatar": "^1.1.11", "@radix-ui/react-scroll-area": "^1.2.10", "@radix-ui/react-slot": "^1.2.4", "@tailwindcss/postcss": "^4.1.18", "ai": "^6.0.86", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "dotenv": "^17.3.1", "drizzle-orm": "^0.45.1", "drizzle-zod": "^0.8.3", "firebase": "^12.9.0", "firebase-admin": "^13.6.1", "lucide-react": "^0.564.0", "next": "~16.0.1", "pg": "^8.18.0", "react": "^19.0.0", "react-dom": "^19.0.0", "react-markdown": "^10.1.0", "remark-gfm": "^4.0.1", "tailwind-merge": "^3.4.0", "tailwindcss": "^4.1.18", "ws": "^8.19.0", "zod": "^4.3.6", "@visa/mcp-client": "file:vendor/visa-mcp/packages/mcp-client", "@visa/token-manager": "file:vendor/visa-mcp/packages/token-manager", "@visa/api-client": "file:vendor/visa-mcp/packages/api-client" } } ``` ### apps/game-server/package.json ``` { "name": "@org/game-server", "version": "0.0.1", "private": true, "type": "module", "dependencies": {} } ``` ### libs/shared-utils/package.json ``` { "name": "@bossroom/shared-utils", "version": "0.0.1", "private": true, "type": "module", "main": "./dist/index.js", "module": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { "./package.json": "./package.json", ".": { "@org/source": "./src/index.ts", "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" } }, "dependencies": { "tslib": "^2.3.0" } } ``` ### libs/shared-types/package.json ``` { "name": "@bossroom/shared-types", "version": "0.0.1", "private": true, "type": "module", "main": "./dist/index.js", "module": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { "./package.json": "./package.json", ".": { "@org/source": "./src/index.ts", "types": "./dist/index.d.ts", "import": "./dist/index.js", "default": "./dist/index.js" } }, "dependencies": { "tslib": "^2.3.0", "zod": "*" } } ``` ### apps/game-frontend/package.json ``` { "name": "@org/game-frontend", "version": "0.0.1", "private": true, "dependencies": { "@bossroom/shared-types": "*", "@bossroom/shared-utils": "*", "@react-three/drei": "^10.7.7", "@react-three/fiber": "^9.5.0", "@react-three/postprocessing": "^3.0.4", "@react-three/rapier": "^2.2.0", "@tanstack/react-query": "^5.90.21", "@tanstack/react-query-devtools": "^5.91.3", "ecctrl": "^1.0.97", "next": "~16.0.1", "peerjs": "^1.5.5", "radix-ui": "^1.4.3", "react": "^19.0.0", "react-dom": "^19.0.0", "simplex-noise": "^4.0.3", "three": "^0.182.0", "zustand": "^5.0.11" }, "devDependencies": { "@types/three": "^0.182.0" } } ``` ### apps/game-server/Dockerfile ``` # BossRoom Game Server # ---- Build stage ---- FROM node:22-slim AS builder WORKDIR /app COPY package*.json ./ COPY apps/game-server/package.json apps/game-server/ COPY apps/game-frontend/package.json apps/game-frontend/ COPY libs/shared-types/package.json libs/shared-types/ COPY libs/shared-utils/package.json libs/shared-utils/ RUN npm ci COPY tsconfig.base.json tsconfig.json nx.json ./ COPY apps/game-server/ apps/game-server/ COPY libs/shared-types/ libs/shared-types/ COPY libs/shared-utils/ libs/shared-utils/ RUN npx nx sync && npx nx build game-server --configuration=production # ---- Production stage ---- FROM node:22-slim WORKDIR /app COPY package*.json ./ COPY apps/game-server/package.json apps/game-server/ COPY apps/game-frontend/package.json apps/game-frontend/ COPY libs/shared-types/package.json libs/shared-types/ COPY libs/shared-utils/package.json libs/shared-utils/ RUN npm ci --omit=dev # Copy built server + workspace lib outputs COPY --from=builder /app/apps/game-server/dist/ apps/game-server/dist/ COPY --from=builder /app/libs/shared-types/dist/ libs/shared-types/dist/ COPY --from=builder /app/libs/shared-utils/dist/ libs/shared-utils/dist/ ENV PORT=8080 EXPOSE 8080 CMD ["node", "apps/game-server/dist/main.js"] ``` ### libs/shared-types/src/index.ts ```typescript export * from './lib/agents.js'; export * from './lib/websocket.js'; export * from './lib/settings.js'; ``` ### libs/shared-utils/src/index.ts ```typescript export * from './lib/agent-defs.js'; export * from './lib/constants.js'; export { createLogger } from './lib/logger.js'; ``` [195 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]