# Typing/Thinking Indicators

Ephemeral events for real-time activity feedback in Nostr conversations.

## Event Kind

**Kind 20001** - Typing/Thinking Indicator (ephemeral)

Per NIP-01, kinds 20000-29999 are ephemeral and should not be stored by relays.

## Event Structure

```json
{
  "kind": 20001,
  "content": "<status>",
  "tags": [
    ["p", "<recipient_pubkey>"],
    ["e", "<thread_root_id>", "", "root"],
    ["e", "<event_being_replied_to>", "", "reply"]
  ],
  "created_at": <unix_timestamp>,
  "pubkey": "<sender_pubkey>",
  "id": "<event_id>",
  "sig": "<signature>"
}
```

### Content Values

| Value | Meaning |
|-------|---------|
| `typing` | User is composing a message |
| `thinking` | Agent is processing/generating |
| `stopped` | Activity stopped (explicit clear) |
| `` (empty) | Clear indicator |

### Tags

- `p` (required): Pubkey of the recipient
- `e` with `root` marker: Thread root event ID
- `e` with `reply` marker: Specific event being replied to

## Client Behavior

### Sending
1. Publish `thinking` when starting to process a message
2. Publish actual response when done
3. Optionally publish `stopped` or empty content to clear early

### Receiving
1. Subscribe to kind 20001 events where you're tagged
2. Display indicator while active
3. Auto-clear after ~15 seconds if no update (stale indicator)
4. Clear immediately when:
   - Receive `stopped` or empty content from same pubkey
   - Receive an actual message (kind 1, 4, 14, etc.) from same pubkey

## Example Flow

```
Agent receives message
  └─> Publish kind:20001 content:"thinking" p:[user]
  └─> Process request...
  └─> Publish kind:1 content:"Here's the answer..." (reply)
  └─> (indicator auto-clears on client when they see the kind:1)
```

## Relay Support

Relays SHOULD:
- Forward ephemeral events to matching subscriptions
- NOT persist ephemeral events to storage
- NOT return ephemeral events in REQ responses for historical data

muxstr handles this correctly as of the ephemeral event support addition.

## Security Considerations

- Indicators reveal that someone is actively engaged with you
- Consider privacy implications before implementing
- Clients MAY offer a setting to disable sending indicators