X-Git-Url: http://git.giacomolli.uk/onechat/blobdiff_plain/97274864799ac2eea84bf80c9727a810b695db55..fc51ee2f545233df3cc1fa2fd4f28a4484c6bc00:/README.rst

diff --git a/README.rst b/README.rst
index c0c6c5d..4bda34e 100644
--- a/README.rst
+++ b/README.rst
@@ -3,8 +3,8 @@
 #########
 
 OneChat is one AI agent in a single chat that never ends. A daemon owns
-the agent and its files, and a terminal client talks to it. It is in
-early development. Linux is supported.
+the agent and its files, and a terminal client and a Telegram bot talk
+to it. It is in early development. Linux is supported.
 
 ****************
  Data directory
@@ -80,9 +80,10 @@ listens on the Unix socket ``onechat.sock`` there. In the client, each
 line is a message to the agent, the line ``/stop`` interrupts the
 running turn, and Ctrl-D ends the client. The client shows the replies,
 the tool calls, and the first lines of each tool result as they happen.
-The daemon is the only process that uses the token file while it runs,
-so ``onechat login`` and ``onechat probe`` refuse to start until it
-stops.
+It also shows each message that the user sends from another client, with
+the client as a mark, such as ``[telegram] text``. The daemon is the
+only process that uses the token file while it runs, so ``onechat
+login`` and ``onechat probe`` refuse to start until it stops.
 
 The agent runs commands with bash as the user in its working directory,
 with no sandbox. It has the rights of the user, also on the token file.
@@ -106,6 +107,43 @@ prompt cache key comes from it.
 how their files are organized, and how they want work done. The prompt
 ends with them, and a change applies at the next call.
 
+**********
+ Telegram
+**********
+
+The daemon also connects the agent to a Telegram bot when
+``telegram.json`` exists in the data directory. It polls the Bot API for
+new messages, so it needs no open port.
+
+#. Make a bot with BotFather and keep its token.
+
+#. Find your numeric Telegram user ID.
+
+#. Write the token and the ID to ``telegram.json``, and give the file
+   mode 0600, because the token is a secret. The daemon refuses the file
+   with any other mode.
+
+#. Start the daemon, open a private chat with the bot, and write.
+
+.. code:: json
+
+   {"token": "123456:ABC-token-from-BotFather", "owner": 123456789}
+
+The bot reads only the private chat of the owner and ignores all other
+updates. Each text message goes to the agent as a user message, and the
+line ``/stop`` interrupts the running turn. The bot sends the replies as
+plain text, in parts of at most 4096 characters, and each error as a
+short message. It shows the typing action while a turn runs. It does not
+send the tool calls. It sends each message that the user types in the
+terminal client, with the mark ``[terminal]``.
+
+``agent/telegram-offset.json`` holds the ID of the next update. The bot
+moves it past an update only after the message is durable in the log, so
+a restart of the daemon does not lose a message. A crash just after the
+write of a message can make the message repeat once. A network failure
+or a rate limit makes the bot wait and try again, and does not stop the
+daemon.
+
 *******
  Probe
 *******