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

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 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: 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: Dependency-free ES6 application managing live polling (5s interval), modal interactions, optimistic updates, and curl drawer telemetry.
• 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:

# 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