wait_for_settled_message

Event-driven, DEBOUNCED wait. Blocks until some private user chat has received one or more incoming messages AND then gone quiet for `settle_ms` — so a client who types several messages (or sends file + text) in a row is delivered as ONE settled burst instead of waking the agent on every message. Returns that chat's burst summary and removes it from the pending set, so the next call returns the next settled chat. If no chat settles within `max_wait_ms`, returns {"event": false, "reason": "timeout"} (caller should simply call again). Recommended usage (replaces blind per-minute polling): call this, get a settled chat, process it (read full history -> draft -> notify -> mark read), call again. Args: settle_ms: Quiet period after the LAST message before a burst is "settled" (default 6000 = 6s). Each new message in the chat resets this timer. max_wait_ms: Max total time to block before returning a timeout (default 50000).

Parameters