Give the WhatsApp batches to the agent

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index fd6cb95b67e99124f6b6254fb51f2d7bf9b10a77..b17cd64349b05077ef6a0c4d6e7db8976c90e154 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -208,6 +208,38 @@ shell of the agent runs as the user, so it can read the session. If the
 session leaks, remove the linked device in WhatsApp on the phone, and
 the session stops working. Without the file, WhatsApp is not linked.
 
+The daemon reads the text messages of the private chats and the groups,
+from other people and from the user. It does not read media, reactions,
+edits, deletions, view-once and disappearing messages, or the history
+from before the link. The messages of one chat form one batch until the
+chat is quiet for 20 seconds, for 2 minutes or 50 messages at the most.
+Each batch goes to the chat of the agent as one work message that starts
+with ``[WhatsApp]``, with the name and the ID of the chat, and the time,
+the sender, and the text of each message. The messages of the user show
+as ``You``. ``whatsapp/state.json``, with mode 0600, keeps the batches
+that are not in the chat yet, so they survive a restart. A crash just
+after a batch goes to the chat can make the batch repeat once.
+
+A batch of a private chat with a message of another person starts a
+turn, and so does a batch of a group with a message that mentions the
+user or replies to a message of the user. The other batches go to the
+chat with no turn, and the agent sees them at its next turn. A batch
+that starts a turn ends with a line that tells the agent to end its turn
+with an empty reply when nothing in the batch needs the user. No client
+shows an empty reply, so such a batch gives no message in Telegram. The
+terminal client shows each batch, and Telegram shows none.
+
+The phone number of the user never goes to the chat: a mention of the
+user shows as ``@you``, the number shows as ``OWN``, and the chat of the
+user with itself is not read. But the IDs of the other chats go to the
+chat and to the model, because the agent needs them to send. The ID of a
+private chat holds the phone number of the contact, such as
+``15550002222@s.whatsapp.net``, and the ID of a group can hold the
+number of the person who made it.
+
+Each batch of a group goes to the chat, also with no turn, and the
+memory tree summarizes it with model calls, which use the quota.
+
 When the session holds a linked device, the daemon connects at its
 start, and after a network failure it connects again by itself. When a
 disconnection lasts 10 minutes, all clients get one notice, and one more