Serve the agent to a terminal client

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index fdcc0e0af17f1c70de0795242da868f4a67fe2e9..c0c6c5d2b16a6457a56a6716229ceb37b8ecd989 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -2,8 +2,9 @@
  OneChat
 #########
 
-OneChat is a Go program. It prints its name. It is in early development.
-Linux is supported.
+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.
 
 ****************
  Data directory
@@ -32,7 +33,7 @@ field is an error.
 
    {
      "endpoint": "chatgpt",
-     "compactor": {"model": "gpt-6-luna", "effort": "high"}
+     "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
    }
 
 ``endpoint``
@@ -43,7 +44,7 @@ field is an error.
 
 ``compactor``
    The model and the reasoning effort of the summaries. The defaults are
-   ``gpt-6-luna`` and ``high``.
+   ``gpt-6.1-sol`` and ``high``.
 
 *******
  Login
@@ -63,6 +64,69 @@ before they expire. The file belongs to OneChat only. Do not share it
 with the Codex CLI, because each program rotates the refresh token and
 logs the other out.
 
+*******
+ Agent
+*******
+
+Start the daemon, and then the client in another terminal:
+
+.. code:: console
+
+   onechat daemon
+   onechat chat
+
+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.
+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.
+
+``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.
+
+.. code:: json
+
+   {
+     "name": "OneChat",
+     "id": "0123456789abcdef0123456789abcdef",
+     "model": "gpt-6.1-sol",
+     "effort": "medium",
+     "workdir": "/home/user"
+   }
+
+``workdir`` is an absolute path, and its default is the home directory.
+``agent/instructions.md`` holds the user's instructions: who they are,
+how their files are organized, and how they want work done. The prompt
+ends with them, and a change applies at the next call.
+
+*******
+ Probe
+*******
+
+``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
+appends the first COUNT messages of LOG, one JSON object ``{"kind",
+"text"}`` on each line, to a new chat in ``probe/`` in the data
+directory, and builds its tree with real model calls. The calls use the
+quota of the account. The run stops at the first failed call, after 660
+calls, or when the used percent of a quota window grows by more than 15
+points. At the end it reports the calls per message, the cached share of
+the input tokens, the retries, the line sizes, and the quota at the
+first and the last call. BUILDS, from 1 to 8, limits the model calls at
+once in the run.
+
+A test writes a generated log of readable made-up messages:
+
+.. code:: console
+
+   ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
+
 *************
  Development
 *************