feat(box): passkey fetch, agent key-approval flow, unified lookups, tmux agent UX
- 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).
This commit is contained in:
operator
+82
-3
@@ -51,7 +51,15 @@ box dm send --agent 646 --to pip --target 646-pip "Hey Pip, start-page onboardin
|
||||
You can directly interact with the headless Muse gateway inside your isolated network namespace using either `muse` or `box muse`:
|
||||
|
||||
```bash
|
||||
# Using native muse wrapper (interactive prompt & account enforcement)
|
||||
# Global lookups & fleet status (no account required)
|
||||
muse status # Complete fleet overview & node vitality
|
||||
muse threads # List registered threads and sidechats across fleet
|
||||
muse unread # View unread counts across all agents
|
||||
muse lookup # Unified lookup (summary of fleet, approvals, unread)
|
||||
muse passkey (or muse key) # Passkey reference (VM .txt location) & agent approval flow
|
||||
muse tmux list # List shared tmux sessions across fleet
|
||||
|
||||
# Using native muse wrapper for per-account actions:
|
||||
muse -a <account> chat # Interactive conversational REPL with thread selection
|
||||
muse -a <account> chat --thread <id> # Direct conversational REPL in specified thread
|
||||
muse -a <account> status
|
||||
@@ -59,19 +67,67 @@ muse -a <account> threads
|
||||
muse -a <account> history --thread <thread_uuid> --limit 10
|
||||
muse -a <account> send --thread <thread_uuid> "<message>"
|
||||
|
||||
# If invoked without -a/--account, it displays valid accounts and usage instructions:
|
||||
# If invoked without arguments, it displays available accounts and commands:
|
||||
muse
|
||||
|
||||
# Alternatively via box CLI:
|
||||
box muse <self> threads
|
||||
box muse status # Cross-fleet status
|
||||
box muse <self> status # Agent-specific status
|
||||
box muse <self> threads # Active sessions for agent
|
||||
box muse <self> history --thread <thread_uuid> --limit 10
|
||||
box muse <self> unread
|
||||
box muse <self> chat # Launch interactive chat REPL
|
||||
box muse <self> session-start --title "<title>"
|
||||
box muse <self> send --thread <thread_uuid> "<message>"
|
||||
box muse tmux list # Direct bridge to muse-tmux manager
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.1. Unified & Seamless Lookups (`box lookup` & `box thread`)
|
||||
|
||||
For fast inspection of fleet state without hunting across multiple tools:
|
||||
|
||||
```bash
|
||||
# Unified lookup summary (fleet health, pending approvals, key reference)
|
||||
box lookup
|
||||
box lookup fleet # Node health, CDP status, active pages
|
||||
box lookup threads # List all registered fleet sidechats and mapped UUIDs
|
||||
box lookup threads <agent> # List active threads for a specific agent
|
||||
box lookup unread # Unread indicators and active tabs across fleet
|
||||
box lookup approvals # Check if any agent is held on browser approvals
|
||||
box lookup key (or box passkey) # Operator passkey & approval protocol
|
||||
|
||||
# Seamless thread inspection:
|
||||
box thread list # List all registered fleet sidechats across agents
|
||||
box thread list <agent> # List active sessions for an agent
|
||||
box thread view <agent> <uuid> # View recent thread messages (supports short UUID prefix)
|
||||
box thread view <agent> "<alias>" # View thread by registered alias (e.g. "646 tasks", "heartbeat")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3.2. Operator Passkey & Key Material Architecture
|
||||
|
||||
> **Crucial Reality**: Key material and administrative passkeys live in a **single file (`.txt`) on the Google Cloud VM (`34.139.37.135`)**. **NO passkeys or secret stores exist on the dedicated BL (`100.123.153.75`)**.
|
||||
|
||||
### Why This Matters:
|
||||
- Front-door console access (`https://box.muse-dev.online/`) is secured by operator PIN `3128` (or the passkey in the VM text file).
|
||||
- Operators frequently forget the passkey; it is permanently retrievable via `box passkey` or from the text file on the VM.
|
||||
- **Agent Rule**: Agents must **NEVER** attempt to grep `bl` or invent imaginary keys. Secrets never reside on the compute node.
|
||||
|
||||
### How Agents Get Key Access / Operator Approval:
|
||||
When an agent or automated task requires elevated privileges, key material, or operator confirmation:
|
||||
1. **Signal the Request**:
|
||||
- In automated scripts: exit with code `2` (the standard `APPROVAL_NEEDED` convention per `INFRA.md`).
|
||||
- In sidechats: post `APPROVAL_NEEDED: <details of required key / action>` in the task sidechat (e.g. `646 tasks`, `pip tasks`, `#jobs`, `heartbeat`).
|
||||
2. **Operator Verification**:
|
||||
- The human operator reviews the request in the sidechat or via `box approvals check`.
|
||||
- If approved, the operator retrieves the key from the single `.txt` file on the VM (or submits transient OTP via `box cred submit-otp`).
|
||||
3. **Execution**:
|
||||
- The operator authorizes the flow or enters the credential transiently. No raw credentials are saved to `bl` or git.
|
||||
|
||||
|
||||
## 4. Shared & Hybrid Tmux Tooling (`muse tmux`, `box tmux`, & `[TOOL tmux.*]`)
|
||||
|
||||
Agents and operators can spawn background sessions and send keystrokes to long-running tasks across three execution tiers:
|
||||
@@ -147,3 +203,26 @@ When jobs are dispatched to agents via `bin/job-dispatch.py`, they are wrapped i
|
||||
2. **Sub-Agent Prioritization**: Break down complex diagnostic or verification jobs by delegating sub-tasks to dedicated subagent threads.
|
||||
3. **Execution Reality**: Work is only real if tool calls ran. Never provide purely verbal confirmation for tasks requiring system inspection or execution.
|
||||
4. **Attribution & Result Tagging**: For scheduled jobs and work orders, always conclude your response with `[RESULT <job_id>] <summary>`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Internal Documentation & Agent Lookups (`box docs` & `docs_internal/`)
|
||||
|
||||
Agents have access to a structured internal `.md` and `.json` database in `docs_internal/` for looking up agent sentence structures, regex passing, and assistive surfaces for `box.muse-dev.online`:
|
||||
|
||||
```bash
|
||||
# Query surfaces, DOM selectors, and REST endpoints for box.muse-dev.online
|
||||
box docs surfaces jobs
|
||||
box docs surfaces dms
|
||||
|
||||
# Inspect agent sentence structures and conversational contracts
|
||||
box docs sentence work_order
|
||||
box docs sentence result
|
||||
|
||||
# Test strings or evaluate against canonical regex patterns
|
||||
box docs regex result --test "[RESULT 7fce46e0] OK 14 endpoints verified"
|
||||
box docs parse "[WO:7fce46e0] [from super] Audit exec — Check stats"
|
||||
|
||||
# Full-text search across documentation database
|
||||
box docs search "work order"
|
||||
```
|
||||
|
||||
@@ -39,12 +39,15 @@ flowchart LR
|
||||
### 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 & Brute-Force Defense**:
|
||||
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**:
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user