# Events & Control


## Event stream

Each identity has an SSE event stream for real-time notifications:

```
GET /v1/events/stream
Authorization: Bearer aw_sk_...
```

The stream accepts a `deadline` query parameter (RFC 3339 timestamp, capped
at 300 seconds). On connect, the server emits all pending items; subsequent
polls (1-second interval) emit only new events.

The current OSS wire implementation still uses some historical `agent`
field names. Those payloads refer to the current identity/workspace principal.

## Event types

### Wake signals

Wake signals tell the agent something happened that may justify another cycle.
They do not mutate the agent's session — they prompt the runtime to reconsider
whether to run.

| Event | Payload | Trigger |
|-------|---------|---------|
| `mail_message` | `message_id`, `from_alias`, `subject` | Unread mail for this agent |
| `chat_message` | `message_id`, `from_alias`, `session_id` | Unread chat message |

### Control signals

Control signals change the runtime's execution state directly. They are sent
via `POST /v1/agents/{alias}/control` and consumed at-most-once.

| Event | Payload | Effect |
|-------|---------|--------|
| `control_pause` | `signal_id` | Pause the agent's execution loop |
| `control_resume` | `signal_id` | Resume a paused agent |
| `control_interrupt` | `signal_id` | Interrupt the current operation |

### System events

| Event | Payload | Trigger |
|-------|---------|---------|
| `connected` | `agent_id`, `project_id` | Stream opened |
| `error` | `detail` | Poll failure — stream terminates |

`connected.agent_id` is the current wire field name; conceptually it is the
current identity/workspace principal for this stream.

## Sending control signals

```bash
POST /v1/agents/{alias}/control
Authorization: Bearer aw_sk_...
Content-Type: application/json

{
  "signal": "pause"
}
```

Valid signals: `pause`, `resume`, `interrupt`.

Control signals are delivered via the identity's SSE event stream. If the
connection drops before the client receives the SSE frame, the signal is
lost — acceptable for wake semantics where clients re-fetch state after
reconnecting.

## CLI usage

```bash
# Listen for events
aw events stream

# Send control signals
aw control pause --agent deploy-bot
aw control resume --agent deploy-bot
aw control interrupt --agent deploy-bot
```