---
name: sst-email-control-loop
description: |
  Long-running pattern for letting a user steer a multi-cycle agent process via email. Each invocation checks the user-control mailbox for new commands, parses them, applies state changes (pause/resume, change frequency, narrow focus, ad-hoc feedback), and sends a concise progress report to the user. Designed to be called once per cycle of an outer loop (e.g. by sst-skill-router or a chained skill); each invocation is self-contained.
user-invocable: true
version: 1.0.1
model-floor: haiku
effort-floor: medium
argument-hint: [path to current cycle state file]
---

# Email control loop

Email is a low-tech, always-on control surface. This skill encodes the pattern for using it to steer a long-running agent process: read inbox, parse commands, update state, send a status report, return.

## Project contract

- **Required env / config** (declared by the project, not by this skill):
  - `EMAIL_CONTROL_FROM` — the address the project sends FROM.
  - `EMAIL_CONTROL_TO` — the user address the project sends TO and accepts commands FROM.
  - Mailbox path the project's mail-IO tool reads (Maildir, IMAP, etc.) — abstracted as the project's `read_mail` / `send_mail` tool pair.
- **State dir**: `<project>/data/sst-email-control-loop/`. Per-cycle state files as `<utc>_<cycle-id>.json`. The skill reads the input state file and writes back a possibly-updated state file at the same path (or a new path if the caller passes `--out`).
- **Tools required**: project's `read_mail` and `send_mail` (variants by project — IMAP, Maildir+procmail, Postmark, SES, etc.); harness's `Read` / `Write` for the state file.
- **Input shape**: a JSON state file with at minimum `{cycle: int, query: str, paused: bool, current_agent: str, loop_results: object, user_commands: object}`.

## Operating principles

- **Idempotent per cycle.** Two invocations on the same cycle should produce the same state changes, not double-apply commands.
- **Don't trust the inbox.** Only read mail FROM the configured `EMAIL_CONTROL_TO` address. Reject anything else silently — don't bounce, don't reply to spam.
- **Don't send a report when paused.** Reading mail still happens (so `/resume` works), but reports are suppressed until the pause clears.
- **Use the right verbosity.** A status report is not a PR announcement. Match the requested `report_frequency` and don't pad.
- **Never echo a token, command body, or sender address back to the user in the report.** Keep the report focused on the agent process, not the comms layer.

## Recognized commands

The user emails plain text; the parser looks for these (case-insensitive, one per line):

| Command            | Effect                                                          |
|--------------------|-----------------------------------------------------------------|
| `pause`            | Sets `state.paused = true`. Skill stops sending reports.        |
| `resume`           | Sets `state.paused = false`. Reports start again next cycle.    |
| `frequency: <N>`   | Sets `state.report_frequency = N` (cycles between reports).     |
| `focus: <topic>`   | Sets `state.user_commands.focus = <topic>`. Other skills can read this to narrow scope. |
| `feedback: <text>` | Appends to `state.user_commands.feedback` for downstream skills to consider. |
| `stop`             | Sets `state.stop_requested = true`. The outer loop should see this and unwind cleanly. |
| (anything else)    | Stored verbatim under `state.user_commands.unparsed` for the user to see in the next report. |

The parser is intentionally simple. Don't try to handle natural language; teach the user the keywords.

## Process

### 1. Read the input state

`Read` the state file. If missing, initialize with `{cycle: 0, query: "", paused: false, current_agent: "init", user_commands: {}}`.

### 2. Check the inbox

Use the project's mail-reading tool to fetch new messages from `EMAIL_CONTROL_TO`. For each:

1. Confirm sender is `EMAIL_CONTROL_TO`. If not, drop silently.
2. Extract the body text.
3. Parse against the recognized-commands table. Apply each match to `state` per the table.
4. Mark the message as read (so the next invocation doesn't re-process it).

### 3. Send a report (if not paused and on schedule)

Conditions for sending:

- `state.paused` is false, AND
- `state.cycle % state.report_frequency == 0`, AND
- `EMAIL_CONTROL_FROM` and `EMAIL_CONTROL_TO` are both set.

Compose the report as plain prose (no salutation, no signature):

```
Iteration <cycle>. Query: <query>.
<one paragraph: what's happened since the last report — which agents/skills
ran, what they produced, any issues encountered, what's next>.
Pause state: <paused | running>.
Report frequency: every <N> cycles.
```

Send via the project's `send_mail` tool. If sending fails, log the error to the state file (`state.last_send_error`) and continue — never abort the loop because mail bounced.

### 4. Save the updated state

Write the state file back. Increment `state.cycle` by 1. Report the path (or `--out` path) as the final line of your response.

## Hard rules

- **Never reply to mail from outside the allowlist.** Silent drop only.
- **Never echo a command back as confirmation.** The next report's "Pause state" / "Report frequency" line IS the confirmation.
- **Never auto-action a `stop` without surfacing it.** Set `state.stop_requested`; the outer loop owns the unwind.
- **Never store mail bodies in the state file.** Parsed state changes only; the original mail goes away (marked read in the inbox).
- **Don't apply commands twice.** Once parsed, the message is marked read. If the inbox re-presents it (e.g. due to a misconfigured server), drop it — duplicate-apply is a worse failure than missing-apply.