X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/97274864799ac2eea84bf80c9727a810b695db55..ec230eee6b06580031637bc97c99ec6db7b41926:/README.rst?ds=sidebyside diff --git a/README.rst b/README.rst index c0c6c5d..3a2d25b 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 @@ -78,8 +78,13 @@ Start the daemon, and then the client in another terminal: The daemon owns the root agent in ``agent/`` in the data directory and 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. +running turn, the line ``/stop NAME`` stops the subagent NAME, 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. It also shows +each message that the user sends from another client, with the client as +a mark, such as ``[telegram] text``. When a subagent starts, the client +shows ``[NAME] started``, and it shows the whole report of the subagent, +which starts with ``[NAME]``, but not the tool calls of the subagent. 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. @@ -87,6 +92,24 @@ 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. +When the user asks for it, the agent starts subagents for long tasks. +Each subagent has a name, such as ``GreenOtter``, and runs in the +background while the agent answers other messages. It gets the view of +the agent and its task, and it runs its tools as the agent does, in +``agent/subagents/NAME/work``. A task in a repository gives the path of +the repository. The steps of a subagent go to its own log in +``agent/subagents/NAME``, not to the chat, and its final reply comes +back to the agent as one message that starts with ``[NAME]``. The agent +can send a subagent more messages: a running subagent reads them between +its tool calls, and a finished one goes on from its log, and its reply +comes back in the same way. When the user stops a subagent, the chat +gets a note, and the report of the subagent is logged, but it starts no +turn. Each model call of a subagent has the name in the ``agent`` field +of ``agent/usage.jsonl``. ``agent/work.json`` holds the names of the +running subagents. A subagent that runs when the daemon stops goes on at +the next start: the chat gets the note that the daemon restarted, and +the subagent gets the same note and goes on from its log. + ``agent/config.json`` holds the settings of the agent. The first start writes it with the defaults and a random ID. Do not change the ID: the prompt cache key comes from it. @@ -106,6 +129,68 @@ 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, the line +``/stop`` interrupts the running turn, and the line ``/stop NAME`` stops +the subagent NAME. The bot sends the replies in parts of at most 4096 +characters, with their Markdown as Telegram formats: bold, italic, +strikethrough, code, code blocks, links, and headings as bold text. When +Telegram refuses the formats of a part, the bot sends the part again as +plain text. Each error goes as a short message in plain text. It shows +the typing action while a turn runs. It does not send the tool calls. +For a subagent it sends only ``[NAME] started`` and ``[NAME] finished``, +``[NAME] stopped``, or ``[NAME] failed``, because the reply of the agent +carries the content of the report. 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. + +********** + WhatsApp +********** + +The daemon connects to the WhatsApp account of the user as a linked +device. In the terminal client or in Telegram, the line ``/whatsapp +status`` shows the link: not linked, linked and connected, or linked and +disconnected, with the times of the connection. The answer goes only to +the client that asked, and the line does not go to the agent. + +The session is ``whatsapp/session.db`` in the data directory. It gives +full access to the WhatsApp account, so the daemon refuses the file when +its mode is not 0600. The 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. When the session holds a linked device, the +daemon connects at its start, and after a network failure it connects +again by itself. + ******* Probe ******* @@ -162,3 +247,6 @@ Format and check all files: bin/format bin/check nix flake check + +``bin/check`` and ``nix build`` run a short replay of the synthetic log. +``nix flake check`` also runs the full replay of 100,000 messages.