box/docs/BOX-WEB-SURFACE-GUIDE.md

# Box Web Surface & Orchestration Architecture

> **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 describes the architecture connecting the **4 autonomous browser agents** (`muse`, `pip`, `646`, `opm`) across `bl` (`100.123.153.75`) and the public Web UI surfaces hosted on the Google Cloud VM (`34.139.37.135` / `box.muse-dev.online`).

---

## 1. Network Topology & Trust Domains

```mermaid
flowchart LR
    subgraph Browser ["Web Client / Operator"]
        UI["box.muse-dev.online\n(PIN 3128)"]
    end

    subgraph Edge ["Cloudflare & Edge"]
        CF["Cloudflare Proxy"]
        Caddy["Caddy (Reverse Proxy & TLS)"]
    end

    subgraph VM ["Google Cloud VM (34.139.37.135)"]
        Board["/srv/board/server.py\n(:8000 Board Service)"]
        Static["/srv/box/www/\n(index.html, box.js, box.css)"]
    end

    subgraph Compute ["Compute Node bl (100.123.153.75)"]
        Bridge["Tailnet SSH Bridge\n(super@100.123.153.75)"]
        Ctl["bin/box-ctl.py & super-cli.py"]
        Agents["Browser NetNS Nodes\n(muse, pip, 646, opm)"]
    end

    UI --> CF --> Caddy
    Caddy -->|Static Files| Static
    Caddy -->|/api/box/*| Board
    Board -->|Allowlisted SSH Verbs| Bridge --> Ctl --> Agents
```

### Trust & Identity Principles
1. **Host as Source of Truth (`bl`)**: All mutating state, cryptographic keys, job definitions, variables, and browser CDP relays reside on `bl`. The VM does not persist authoritative fleet state.
2. **On-Demand Tailnet SSH Bridge**: The VM board service bridges into allowlisted verbs in [`bin/box-ctl.py`](file:///home/super/Projects/NetVM/bin/box-ctl.py) using an on-demand Tailnet SSH connection (`super@100.123.153.75`).
3. **Session Authentication & Passkey Location Reality**:
   - Operator console access is unlocked via `POST /api/ops/login` with operator PIN `3128`, establishing cookie `ops_session`.
   - **Crucial Passkey Reality**: In reality, the passkey material is stored in a **single file (`.txt`) on the Google Cloud VM (`34.139.37.135`)**, **NOT on the dedicated BL (`100.123.153.75`)**.
   - Operators frequently forget this passkey; retrieve anytime via `box passkey` or from the text file on the VM.
   - Successful PIN logins bypass the rate limiter. Failed attempts are constrained by a 10-attempt sliding window.
4. **Agent-Scoped Privacy Tiers & Approval Flow**:
   - `ops_session` grants unredacted administrative visibility across all DMs, logs, loops, and actions.
   - Unauthenticated or agent-scoped queries receive redacted logs filtered to their respective identities.
   - **Agent Key Requests**: Agents do not hold administrative keys directly and must never hunt on `bl` for secrets. When elevated key access or approval is required, agents signal `APPROVAL_NEEDED: <details>` in task sidechats (or exit code 2). Operators verify and fulfill from the single `.txt` file on the VM.

---

## 2. API Surface Catalog

### Fleet & Messaging Endpoints
* **`GET /api/box/fleet`**: Real-time CDP latency, node status, current page titles, and queue depths across all 4 nodes (`muse`, `pip`, `646`, `opm`).
* **`GET /api/box/dm/log?limit=N`**: Chronological stream of signed Work Orders, Jobs, and agent responses.

### Job & Timer Automation
* **`GET /api/box/timers`**: Active systemd timer schedules and registered jobs.
* **`POST /api/box/jobs/{name}/trigger`**: Asynchronous hot-trigger calling `box-ctl.py job-trigger <name>`. Returns `202 Accepted` immediately without blocking the browser turn.

### Intrinsic Loop & Strategy Mutators (Stage 2)
* **`GET /api/box/loop/health`**: Real-time ratio of answered+closed loops vs landed loops with health verdicts.
* **`GET /api/box/loop/status`**: Detailed list of open loops, deadlines, and nudge counts.
* **`GET /api/box/loop/strat`**: Hierarchy of strategy policies.
* **`POST /api/box/loop/strat`**: Mutate strategy policy (`type`, `subtype`, `priority`, `timeout_s`, `nudges`, `escalate`).
* **`POST /api/box/loop/strat/reset`**: Reset a custom strategy override to built-in defaults.
* **`GET /api/box/loop/vars`**: Dynamic runtime control variables with full validation schema and units.
* **`POST /api/box/loop/vars`**: Mutate a runtime control variable (`name`, `value`).
* **`POST /api/box/loop/vars/reset`**: Reset a variable to its default value.
* **`GET /api/box/loop/vars/history?name=...`**: Audit trail of variable mutations and rollbacks.

---

## 3. Web Console Architecture (`/srv/box/www/`)

* **[`index.html`](file:///home/super/Projects/NetVM/web/box/www/index.html)**: Clean, single-page application structure supporting 4 dedicated views:
  1. **Fleet Pulse & Node Cards**
  2. **Live DM & Work Order Stream** (with search and tag filtering)
  3. **Timers & Scheduled Jobs** (with `▶ Run` hot triggers)
  4. **Loops, Strategy Matrix & Runtime Variables** (with interactive edit/reset modals)
* **[`box.js`](file:///home/super/Projects/NetVM/web/box/www/box.js)**: Dependency-free ES6 application managing live polling (5s interval), modal interactions, optimistic updates, and curl drawer telemetry.
* **[`box.css`](file:///home/super/Projects/NetVM/web/box/www/box.css)**: Responsive terminal dark theme.

---

## 4. Operational Runbook

### Hot-Triggering a Fleet Health Audit
1. Navigate to **Timers & Jobs** on `https://box.muse-dev.online/`.
2. Click **▶ Run** on `box-http-health`.
3. The button updates to `Triggering...` then `✓ Sent`.
4. The background job dispatches via `646`, runs HTTP assertions, and records a `[RESULT ...]` in `job-log.jsonl`.

### Dynamically Tuning Runtime Variables
To adjust nudge limits without restarting services:
```bash
# Via Web Console: Navigate to Loop & Strategy tab -> Click "✎ Edit" on max_nudge_count
# Or via CLI on bl:
super vars set max_nudge_count 3
super vars get max_nudge_count
```