Back up the daemon and restore its data

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index 9893fc40944ca89fc6675e97ebb724036d901b1a..929272c9167c1a96b45116f05f56d88cf0531682 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -82,15 +82,19 @@ 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, the line ``/stop NAME`` stops the subagent NAME, 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, 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.
+Ctrl-D ends the client. On terminal output, the client shows ``> ``
+after each event while idle and clears it before the next event. An
+event can interrupt a line while the user types. The client shows the
+replies, the tool calls, and the first lines of each tool result as they
+happen. Replies and subagent reports render Markdown with styles and
+wrapped tables only when the output is a terminal, and stay unchanged in
+a pipe or file. 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.

 
 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.
 
 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.


@@ -219,6 +223,34 @@ login. To stop it, or also remove its start at login:
    systemctl --user stop onechat.service
    systemctl --user disable onechat.service
 
    systemctl --user stop onechat.service
    systemctl --user disable onechat.service
 

+************
+ Daemon log
+************
+
+The daemon writes short events with the part prefix and ordered
+``key=value`` attributes. An error cause comes last. Normal events use
+info, failures that can be retried or lose nothing use warning, and
+failures that lose data or stop work use error.
+
+With ``JOURNAL_STREAM`` set, each line carries a syslog priority without
+a time stamp or level word. The user journal can show only warnings and
+errors:
+
+.. code:: console
+
+   journalctl --user -u onechat -p warning
+
+The summary warning names its node. A schedule run has ``late`` only
+when it ran late:
+
+.. code:: text
+
+   <4>onechat: summary failed level=0 index=0: fake failure
+   <6>onechat: schedule ran id=1
+   <6>onechat: schedule ran id=2 late=1m0s
+
+Outside the journal, each line starts with the time stamp and level.
+

 **********
  Telegram
 **********
 **********
  Telegram
 **********


@@ -401,13 +433,14 @@ exports before import: their text goes to the model as chat history.
 
 The import merges the full log in date order and builds its tree with
 real compactor calls, the agent prompt, and the agent cache key. It uses
 
 The import merges the full log in date order and builds its tree with
 real compactor calls, the agent prompt, and the agent cache key. It uses

-the probe's 660-call and 15-quota-point limits and prints the same usage
-report. Its estimate is about 1.3 calls per merged message, not a cost
-guarantee. A stopped or failed run leaves the agent unchanged. A new run
-starts over. Success keeps the other agent files and renames the old
-directory to ``agent-backup-TIMESTAMP`` before it installs the new one.
-Keep the backup until the new memory is checked, then start the daemon.
-Message IDs change to their positions in the merged log.
+a limit of 1,500 calls and the probe's 15-quota-point limit, and prints
+the same usage report. Its estimate is about 1.3 calls per merged
+message, not a cost guarantee. A stopped or failed run leaves the agent
+unchanged. A new run starts over. Success keeps the other agent files
+and renames the old directory to ``agent-backup-TIMESTAMP`` before it
+installs the new one. Keep the backup until the new memory is checked,
+then start the daemon. Message IDs change to their positions in the
+merged log.

 
 ***********
  Schedules
 
 ***********
  Schedules


@@ -498,6 +531,9 @@ Build and run:
    nix build
    ./result/bin/onechat
 
    nix build
    ./result/bin/onechat
 

+``onechat version`` prints ``yyyy-mm-dd-gitshort`` for a Nix build, adds
+``-dirty`` for a dirty tree, and prints ``dev`` for a direct Go build.
+

 Format and check all files:
 
 .. code:: console
 Format and check all files:
 
 .. code:: console