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).
2026-10-05 20:18:47 +00:00
parent 59c9965791
commit adfcd2e602
38 changed files with 5948 additions and 168 deletions
@@ -0,0 +1,153 @@
+# Agent Sentence Structures & Conversational Grammar
+
+> **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 and protocol grammar.
+
+This master document defines the standardized sentence structures, bracketed markers, conversational contracts, and grammar rules governing autonomous agent communication across NetVM and Box.
+
+---
+
+## 1. Overview & Protocol Lifecycle
+
+Agent communication relies on structured, machine-parsable prefixes embedded into natural language sentences. This allows human operators and autonomous language models to read the same stream while automation engines (`response-harvester.py`, `followup-sweeper.py`, `self_main_loop.py`) extract telemetry, update loop states, and trigger downstream events.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Dispatched: [WO:id] Work Order
+    Dispatched --> Acknowledged: [ACK:id]
+    Dispatched --> Claimed: [CLAIM id]
+    Acknowledged --> Claimed: [CLAIM id]
+    Claimed --> Running: [TOOL op args] / execution
+    Running --> Resolved: [RESULT id] OK <summary>
+    Claimed --> Declined: [DECLINE id] <reason>
+    Claimed --> NoAction: [NO-ACTION id] <reason>
+    Running --> Nudged: [NUDGE id] (SLA warning)
+    Nudged --> Resolved: [RESULT id]
+    Resolved --> [*]
+    Declined --> [*]
+    NoAction --> [*]
+```
+
+---
+
+## 2. Core Sentence Structures
+
+### 2.1 Work Order (`[WO:<id>]`)
+* **Purpose**: Tasking dispatched across operators or from the off-board orchestrator. Creates a tracked loop with an SLA deadline.
+* **Format**:
+  ```text
+  [WO:<dm_id>] [from <sender>] <title> — <body>
+  ```
+* **Required Components**:
+  - `dm_id`: Unique identifier (hex string, e.g. `7fce46e0`).
+  - `sender`: Author identity (`super`, `646`, `pip`, `opm`, `muse`).
+  - `title`: Short task description.
+  - `body`: Detailed instructions and acceptance criteria.
+* **Example**:
+  ```text
+  [WO:8a12bc44] [from super] Audit exec.muse-dev.online endpoints — Verify that allowlisted ops respond with 200 OK.
+  ```
+
+### 2.2 Acknowledgement (`[ACK:<id>]`)
+* **Purpose**: Confirms delivery and receipt of a Work Order or message, preventing re-dispatch.
+* **Format**:
+  ```text
+  [ACK:<dm_id>] [from <sender>]
+  ```
+* **Example**:
+  ```text
+  [ACK:8a12bc44] [from 646]
+  ```
+
+### 2.3 Task Claim (`[CLAIM <id>]`)
+* **Purpose**: Declares exclusive ownership of a task or swarm worker slot.
+* **Format**:
+  ```text
+  [CLAIM <job_id>]
+  ```
+* **Example**:
+  ```text
+  [CLAIM 8a12bc44]
+  ```
+
+### 2.4 Task Completion Result (`[RESULT <id>]`)
+* **Purpose**: Delivers final evidence or outcome, closing the active loop and recording success/failure in `job-log.jsonl`.
+* **Format**:
+  ```text
+  [RESULT <job_id>] <status> <summary>
+  ```
+  *(Status options: `OK`, `FAIL`, `SUCCESS`, `DECLINE`)*
+* **Example**:
+  ```text
+  [RESULT 8a12bc44] OK Verified 14 endpoints; all return valid 200 responses with expected schemas.
+  ```
+
+### 2.5 Task Decline & No-Action
+* **Decline Format**:
+  ```text
+  [DECLINE <job_id>] <reason>
+  ```
+* **No-Action Format**:
+  ```text
+  [NO-ACTION <job_id>] <reason>
+  ```
+
+### 2.6 In-Band Tool Calls (`[TOOL <op> <args>]`)
+* **Purpose**: Inline directive parsed by `response-harvester.py` and executed directly on the host or inside a node netns.
+* **Format**:
+  ```text
+  [TOOL <op> <args_json>]
+  ```
+* **Example**:
+  ```text
+  [TOOL followup.create {"in_m": 5, "prompt": "Re-check Cloudflare WARP proxy status"}]
+  ```
+
+### 2.7 Loop Followup Nudge (`[NUDGE <id>]`)
+* **Purpose**: Automated escalation sent to an agent when an SLA deadline is approaching or breached.
+* **Format**:
+  ```text
+  [NUDGE <loop_id>] [nudge <count>/<max_nudges>] Deadline <time_utc>: <prompt>
+  ```
+* **Example**:
+  ```text
+  [NUDGE 8a12bc44] [nudge 1/3] Deadline 19:45 UTC: Please confirm status of exec audit.
+  ```
+
+### 2.8 Fleet Alert (`[fleet-alert]`)
+* **Purpose**: Infrastructure health broadcasts dispatched to `#lobby` and `#jobs`.
+* **Format**:
+  ```text
+  [fleet-alert] <SEVERITY>: <message>
+  ```
+* **Example**:
+  ```text
+  [fleet-alert] CRITICAL: VM unreachable x2 on port 22
+  ```
+
+---
+
+## 3. Conversational Contract Footer
+
+When issuing prompts to model instances, orchestrators append the **Contract Footer**:
+```text
+Reply: [ACK id] seen | [CLAIM id] mine | [RESULT id] done | [DECLINE id] | [NO-ACTION id].
+```
+This forces strict conformance to parsable reply tokens.
+
+---
+
+## 4. Querying from CLI
+
+Agents and operators can look up these sentence structures using the unified CLI:
+```bash
+# View list of all structures
+super docs sentence
+box docs sentence
+
+# View specific structure specification
+super docs sentence work_order
+super docs sentence result
+
+# Validate or parse an utterance
+super docs parse "[WO:7fce46e0] [from super] Run audit — check endpoints"
+```