Concepts
The floor
The office's home page in three views (List, 2D map, 3D office), fed by a permission-filtered JSON endpoint and live updates.
The Floor (/) is the first page after sign-in: every agent you may see, what it is doing right now, and what it has spent today. It needs office.read (every role has it).
Above the agents are four stats: on duty, working now, needs you, and spend today against the combined daily budget. A segmented switch in the page header picks one of three views of the same data.
| View | What it shows |
|---|---|
| List | One card per agent: role, department, status, the run it is working on, new mail, and today's spend against its budget, with Chat for agents you may chat with. |
| 2D | A top-down map of the office. Departments are zones, agents sit at desks in pods, and you sit in the lounge. Pan by dragging, zoom with the wheel, a pinch or the buttons, and Fit to see everything. Hover a desk for details; click it to open the agent's desk. |
| 3D | The same layout as a small 3D office, drawn with three.js and no external assets. Working agents type, their monitor glows and a status chip floats above them. Drag to orbit, scroll to zoom, click someone to open their desk. |
Your choice is remembered in this browser, and ?view=list, ?view=2d or ?view=3d in the URL overrides it, so a link opens a specific view. The 2D and 3D views are loaded only when you open them (three.js only for 3D). Without JavaScript, the page is the server-rendered list.
Desks are ordered by when each agent joined, so a new hire gets a new desk and never moves anyone else's. When mail arrives while you watch, an envelope flies from the sender's desk to the recipient's.
What the floor knows: GET /api/floor#
The 2D and 3D views read GET /api/floor (session cookie, permission office.read, Cache-Control: no-store). It returns ids, names and numbers only:
| Field | Contents |
|---|---|
office, now | Office name and the server time. |
viewer | Your name (for the lounge). |
departments | Each department with its agent count. |
agents | Per agent: slug, name, role, roleTitle, department, status, manager (a display name), since, working (run id, kind, label such as Mail #12, start time) or null, queued runs, unreadMail, needsYou, spendToday, budget, lastActive. |
mail | Recent mail as edges: from (an agent slug, or human), fromKind, to, at. The last 60 minutes, at most 60 edges, newest first. |
It is filtered by your permissions before it leaves the server:
- Agents are those you hold
agent.readon; retired agents are left out. - Unread mail is counted only for agents whose mail you may read (
mail.read); otherwise it is0. - Needs you counts the agent's pending approvals that you may see (
approval.read). - Mail edges carry no subjects or bodies, and a human sender is never named, only
human. An edge is included only when you can see the recipient and, for agent-to-agent mail, the sender too.
Live updates#
The floor listens to the office's live-updates stream (/events, server-sent events) for run, mail, agent and approval changes, and refetches /api/floor when one arrives (at most about once every 0.7 seconds). It also refreshes every 30 seconds while the tab is visible, and when you come back to the tab. The status line shows Live while the stream is connected. The stream itself is permission-filtered: you only receive events about agents you may see.
Motion and fallbacks#
- Reduced motion. With the system setting reduce motion on, envelopes appear at their destination instead of flying, the 3D camera doesn't animate in, and the 3D scene is drawn only when something changes.
- No WebGL. If the browser can't start WebGL, the 3D view says so and links to the 2D map.
- Hidden tab. The 3D view pauses when it is hidden or scrolled off-screen.
- Themes. Both maps take their colours from the page's light or dark theme and switch with it.