git.giacomolli.uk - onechat/blob - README.rst

   1 #########
   2  OneChat
   3 #########
   4
   5 OneChat is one AI agent in a single chat that never ends. A daemon owns
   6 the agent and its files, and a terminal client and a Telegram bot talk
   7 to it. It is in early development. Linux is supported.
   8
   9 ****************
  10  Data directory
  11 ****************
  12
  13 OneChat keeps its data and its token file in one directory. It uses the
  14 first of these:
  15
  16 #. ``ONECHAT_DIR``, when it is set.
  17 #. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute
  18    path. A relative value is ignored.
  19 #. ``~/.local/share/onechat``. With no home directory, OneChat exits
  20    with an error.
  21
  22 OneChat creates the directory with mode 0700.
  23
  24 ***************
  25  Configuration
  26 ***************
  27
  28 ``config.json`` in the data directory holds the settings. OneChat does
  29 not create it. A missing file or field takes the default, and an unknown
  30 field is an error.
  31
  32 .. code:: json
  33
  34    {
  35      "endpoint": "chatgpt",
  36      "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
  37    }
  38
  39 ``endpoint``
  40    ``chatgpt`` (the default) sends model calls to the ChatGPT backend
  41    with the subscription login. ``api`` sends them to the OpenAI API
  42    with the key in ``OPENAI_API_KEY``, which must then be set. With
  43    ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``.
  44
  45 ``compactor``
  46    The model and the reasoning effort of the summaries. The defaults are
  47    ``gpt-6.1-sol`` and ``high``.
  48
  49 *******
  50  Login
  51 *******
  52
  53 The ``chatgpt`` endpoint needs a login with a ChatGPT account:
  54
  55 .. code:: console
  56
  57    onechat login
  58
  59 The command shows a link and a code. Open the link on any device, enter
  60 the code, and approve the login. Device code login must be allowed in
  61 the ChatGPT security settings. OneChat writes the tokens to
  62 ``auth.json`` in the data directory, with mode 0600, and refreshes them
  63 before they expire. The file belongs to OneChat only. Do not share it
  64 with the Codex CLI, because each program rotates the refresh token and
  65 logs the other out.
  66
  67 *******
  68  Agent
  69 *******
  70
  71 Start the daemon, and then the client in another terminal:
  72
  73 .. code:: console
  74
  75    onechat daemon
  76    onechat chat
  77
  78 The daemon owns the root agent in ``agent/`` in the data directory and
  79 listens on the Unix socket ``onechat.sock`` there. In the client, each
  80 line is a message to the agent, the line ``/stop`` interrupts the
  81 running turn, and Ctrl-D ends the client. The client shows the replies,
  82 the tool calls, and the first lines of each tool result as they happen.
  83 It also shows each message that the user sends from another client, with
  84 the client as a mark, such as ``[telegram] text``. The daemon is the
  85 only process that uses the token file while it runs, so ``onechat
  86 login`` and ``onechat probe`` refuse to start until it stops.
  87
  88 The agent runs commands with bash as the user in its working directory,
  89 with no sandbox. It has the rights of the user, also on the token file.
  90
  91 When the user asks for it, the agent starts subagents for long tasks.
  92 Each subagent has a name, such as ``GreenOtter``, and runs in the
  93 background while the agent answers other messages. It gets the view of
  94 the agent and its task, and it runs its tools as the agent does, in
  95 ``agent/subagents/NAME/work``. A task in a repository gives the path of
  96 the repository. The steps of a subagent go to its own log in
  97 ``agent/subagents/NAME``, not to the chat, and its final reply comes
  98 back to the agent as one message that starts with ``[NAME]``. The agent
  99 can send a subagent more messages: a running subagent reads them between
 100 its tool calls, and a finished one goes on from its log, and its reply
 101 comes back in the same way. Each model call of a subagent has the name
 102 in the ``agent`` field of ``agent/usage.jsonl``.
 103
 104 ``agent/config.json`` holds the settings of the agent. The first start
 105 writes it with the defaults and a random ID. Do not change the ID: the
 106 prompt cache key comes from it.
 107
 108 .. code:: json
 109
 110    {
 111      "name": "OneChat",
 112      "id": "0123456789abcdef0123456789abcdef",
 113      "model": "gpt-6.1-sol",
 114      "effort": "medium",
 115      "workdir": "/home/user"
 116    }
 117
 118 ``workdir`` is an absolute path, and its default is the home directory.
 119 ``agent/instructions.md`` holds the user's instructions: who they are,
 120 how their files are organized, and how they want work done. The prompt
 121 ends with them, and a change applies at the next call.
 122
 123 **********
 124  Telegram
 125 **********
 126
 127 The daemon also connects the agent to a Telegram bot when
 128 ``telegram.json`` exists in the data directory. It polls the Bot API for
 129 new messages, so it needs no open port.
 130
 131 #. Make a bot with BotFather and keep its token.
 132
 133 #. Find your numeric Telegram user ID.
 134
 135 #. Write the token and the ID to ``telegram.json``, and give the file
 136    mode 0600, because the token is a secret. The daemon refuses the file
 137    with any other mode.
 138
 139 #. Start the daemon, open a private chat with the bot, and write.
 140
 141 .. code:: json
 142
 143    {"token": "123456:ABC-token-from-BotFather", "owner": 123456789}
 144
 145 The bot reads only the private chat of the owner and ignores all other
 146 updates. Each text message goes to the agent as a user message, and the
 147 line ``/stop`` interrupts the running turn. The bot sends the replies in
 148 parts of at most 4096 characters, with their Markdown as Telegram
 149 formats: bold, italic, strikethrough, code, code blocks, links, and
 150 headings as bold text. When Telegram refuses the formats of a part, the
 151 bot sends the part again as plain text. Each error goes as a short
 152 message in plain text. It shows the typing action while a turn runs. It
 153 does not send the tool calls. It sends each message that the user types
 154 in the terminal client, with the mark ``[terminal]``.
 155
 156 ``agent/telegram-offset.json`` holds the ID of the next update. The bot
 157 moves it past an update only after the message is durable in the log, so
 158 a restart of the daemon does not lose a message. A crash just after the
 159 write of a message can make the message repeat once. A network failure
 160 or a rate limit makes the bot wait and try again, and does not stop the
 161 daemon.
 162
 163 *******
 164  Probe
 165 *******
 166
 167 ``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
 168 appends the first COUNT messages of LOG, one JSON object ``{"kind",
 169 "text"}`` on each line, to a new chat in ``probe/`` in the data
 170 directory, and builds its tree with real model calls. The calls use the
 171 quota of the account. The run stops at the first failed call, after 660
 172 calls, or when the used percent of a quota window grows by more than 15
 173 points. At the end it reports the calls per message, the cached share of
 174 the input tokens, the retries, the line sizes, and the quota at the
 175 first and the last call. BUILDS, from 1 to 8, limits the model calls at
 176 once in the run.
 177
 178 A test writes a generated log of readable made-up messages:
 179
 180 .. code:: console
 181
 182    ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
 183
 184 *************
 185  Development
 186 *************
 187
 188 Nix supplies the Go toolchain and all tools. Enter the development shell
 189 with direnv:
 190
 191 .. code:: console
 192
 193    direnv allow
 194
 195 Or enter it directly:
 196
 197 .. code:: console
 198
 199    nix develop
 200
 201 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
 202 unless it is already set. Development data goes there, and Git ignores
 203 ``.devenv``.
 204
 205 Build and run:
 206
 207 .. code:: console
 208
 209    nix build
 210    ./result/bin/onechat
 211
 212 Format and check all files:
 213
 214 .. code:: console
 215
 216    bin/format
 217    bin/check
 218    nix flake check
 219
 220 ``bin/check`` and ``nix build`` run a short replay of the synthetic log.
 221 ``nix flake check`` also runs the full replay of 100,000 messages.