From 975acc2bf48ddbd98d58864ba04f95b2fcca6803 Mon Sep 17 00:00:00 2001
From: Clawd <ai@clawd.bot>
Date: Sun, 8 Mar 2026 09:58:35 -0700
Subject: Add ephemeral event support (kinds 20000-29999)

Per NIP-01, ephemeral events are broadcast to subscribers but not
persisted to storage. This enables real-time features like typing
indicators without bloating the database.

Also adds typing-indicators.md spec for kind 20001.
---
 docs/typing-indicators.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 docs/typing-indicators.md

(limited to 'docs')

diff --git a/docs/typing-indicators.md b/docs/typing-indicators.md
new file mode 100644
index 0000000..a85633d
--- /dev/null
+++ b/docs/typing-indicators.md
@@ -0,0 +1,80 @@
+# 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", "<event_id_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` (optional): Event being replied to, with `reply` marker
+
+## 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
-- 
cgit v1.2.3