operator
adfcd2e602
- box passkey [show|fetch] (+ muse passkey): documents VM-only passkey (/srv/box/passkey.txt, fallback /etc/netvm/passkey.txt on 34.139.37.135), probes VM over SSH with graceful fallback; --json supported. No secrets on bl. - approvals: request_key_approval / check_node_key_request; KEY_APPROVAL status surfaced in `box approvals check`; allow/deny resolve + audit to box-ctl.jsonl; never auto-approved. New `box approvals request-key <node> --reason`. - box lookup (summary|fleet|threads|unread|approvals|key|docs) and docs-lookup engine with lookup_internal/ database (docs_internal symlink). - muse-tmux: non-TTY attach falls back to scrollback capture; prune NameError fix. - box/muse passthrough for tmux/muse/docs; thread list/view alias + prefix resolve. - Docs: AGENTS.md, AGENT-TOOLING.md, BOX-WEB-SURFACE-GUIDE.md, README. - Tests: key-approval + passkey tests; sync stale sidechat UUIDs and manifest name. - .gitignore runtime trackers (subagent-sessions, conversation-nudge-tracker).
105 lines
5.8 KiB
Markdown
105 lines
5.8 KiB
Markdown
# 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
|
|
```
|