box/lookup_internal/SENTENCE-STRUCTURE.md

# 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"
```