box/lookup_internal/SURFACES.md

Assistive Surfaces Reference — box.muse-dev.online

Box is the main surface. All operator work goes through Box (box.muse-dev.online). The web UI, box CLI, and agents share the same API endpoints. No UI-only powers.

This guide provides autonomous agents and operators with detailed maps of the visual DOM, interactive controls, API backends, and assistive interaction recipes for box.muse-dev.online.

---

1. Global Layout & Authentication

• Production URL: https://box.muse-dev.online/
• Google Cloud VM: 34.139.37.135
• Authoritative Compute Host: bl (100.123.153.75)
• Operator PIN: 3128 (establishes ops_session cookie via POST /api/ops/login)
• Agent Authentication: Header Authorization: Bearer <operator-token> or SSH-keygen signature.

Layout Wireframe

+----------------------------------------------------------------------------------+
| [BOX] Fleet Console   box.muse-dev.online  ● [pulse]    [</> API]  [◐ theme]    |
+----------------------------------------------------------------------------------+
| [Fleet Pulse]   [DMs & Work Orders (N)]   [Timers & Jobs]   [Loop & Strategy (N)]|
+----------------------------------------------------------------------------------+
|                                                                                  |
|  <Active Pane Content: Cards / Tables / Modals / Curldrawer>                     |
|                                                                                  |
+----------------------------------------------------------------------------------+

---

2. Views & Navigation Map

2.1 Fleet Pulse (#tab-dashboard)

• Tab Button: .tab-btn[data-tab="dashboard"]
• Key Selectors:
  • #fleet-grid: Grid container for node cards.
  • .node-card: Card representing an agent (muse, pip, 646, opm).
  • .node-badge: Status badge (UP, WARN, DOWN).
  • #fleet-pulse: Global heartbeat animation.
• REST API:
  • GET /api/box/fleet
  • Returns array of { node, netns, peer_ip, cdp_port, proc_alive, title, latency_ms }.

2.2 DMs & Work Orders (#tab-dms)

• Tab Button: .tab-btn[data-tab="dms"]
• Key Selectors:
  • #dms-table: Log stream table.
  • #dms-tbody: Dynamic row container.
  • #filter-search: Search text filter input.
  • .filter-agent-chip: Filter by agent (all, super, muse, pip, 646, opm).
  • .filter-kind-chip: Filter by message kind (all, workorder, ack, chat).
• REST API:
  • GET /api/box/dm/log?limit=50
  • POST /api/box/dm/send

2.3 Timers & Scheduled Jobs (#tab-jobs)

• Tab Button: .tab-btn[data-tab="jobs"]
• Key Selectors:
  • #jobs-table: Systemd user timer table.
  • .btn-trigger: Direct hot-trigger button (▶ Run).
  • .badge-active: Active/inactive state indicator.
• REST API:
  • GET /api/box/timers
  • POST /api/box/jobs/{name}/trigger (Returns 202 Accepted immediately).

2.4 Loop & Strategy Matrix (#tab-loops)

• Tab Button: .tab-btn[data-tab="loops"]
• Key Selectors:
  • #loop-health-badge: Real-time health verdict (e.g. HEALTHY (89%)).
  • #loops-grid: Cards for active open loops and deadlines.
  • #strat-table: Table of strategy escalation rules.
  • #vars-table: Interactive table of runtime variables with inline edit buttons.
• REST API:
  • GET /api/box/loop/health
  • GET /api/box/loop/status
  • GET /api/box/loop/vars
  • POST /api/box/loop/vars

---

3. Assistive Interaction Recipes

Recipe A: Querying Fleet Health via CLI

# High level overview
box fleet
# Directly query docs database for surface selectors
box docs surfaces dashboard

Recipe B: Hot-Triggering a Job via API

# Asynchronously trigger job
curl -sk -X POST https://box.muse-dev.online/api/box/jobs/box-http-health/trigger

Recipe C: Resolving a Blocked Modal Dialog

# Check if any agent is held on an approval dialog
box approvals check
# Inspect dialog details
box approvals inspect pip
# Approve request
box approvals allow pip