X-Git-Url: http://git.giacomolli.uk/onechat/blobdiff_plain/ae8532ff0e9d3d676fec5f48780a62e58aa6882d..5a93b6124068c2a8748fc0bfbb2a2d151815bcf0:/README.rst?ds=inline diff --git a/README.rst b/README.rst index 929272c..556ab46 100644 --- a/README.rst +++ b/README.rst @@ -138,6 +138,40 @@ ends with them, and a change applies at the next call. The agent can propose a change to the file, and it makes the change only after the user agrees. +A permanent child agent lives in ``agent/children/NAME/`` with the same +files as the root. The root's ``agent_create(name, responsibility)`` +tool creates and starts it with the root's model, effort, and working +directory, and a separate random ID. A name describes the area, such as +``House`` or ``Calendar``. It is one word of 2 to 32 ASCII letters, +starts with a capital letter, and cannot name the root, an existing +child, or a subagent. The daemon opens all children at startup. A +missing or invalid child config stops startup. Only one level of +children is supported. Remove a child by hand while the daemon is +stopped. The root's turn state lists each child and its responsibility. +The root passes area messages from mixed chats with sender, date, and +words, and asks the user before it sends a child's draft to WhatsApp. + +Each child has its own memory, model client, usage file, subagents, +schedules, and turn loop. Its prompt limits work to its area, asks for +only reports that need the parent or the user, and permits an empty +reply. Children have no WhatsApp tools and draft replies instead of +sending them. Clients and WhatsApp still address only the root. A +child's saved schedules and subagents can resume at startup. The ready +log line lists the child names. + +A message from a parent to its own child enters the child's log as +``user`` and wakes it. A child's final reply reaches the parent as +``work`` with the prefix ``[NAME] `` and wakes it. An empty reply sends +nothing. A busy recipient takes the message between tool calls or in its +next turn. ``agent/messages.json``, with mode 0600, keeps messages until +their recipient finishes its turn. A daemon stop preserves queued +messages and reports for the next start without a second log entry. An +interrupted turn can repeat its model calls and tools after restart. +Backups lock this queue with the agent files, including children made +during the daemon run. The root uses ``tell`` for both children and +subagents. ``zoom("Name")`` gives a child's view or a subagent's whole +log. ``spawn`` starts short-lived subagents, not permanent children. + ************** User service ************** @@ -223,6 +257,100 @@ login. To stop it, or also remove its start at login: systemctl --user stop onechat.service systemctl --user disable onechat.service +******************** + Backup and restore +******************** + +Back up the running daemon to one mode 0600 ``.tar.gz`` archive. The +command prints its path and size in bytes. With no daemon, it fails. + +.. code:: console + + onechat backup BACKUP_FILE.tar.gz + ONECHAT_DIR=EMPTY_DATA_DIR onechat restore BACKUP_FILE.tar.gz + +The daemon flushes memory and holds its write locks during the agent +copy. It also flushes and locks the child agents and all subagent logs. +It copies the WhatsApp session with SQLite ``VACUUM INTO``, not as raw +database files. It then compresses the copy and installs the archive +through a temporary file and a rename. Use a backup path outside the +data directory. + +The archive includes configuration, instructions, the log, tree, +indexes, views, layout, schedules, subagents, children, Telegram offset, +tokens, and WhatsApp state and session. It excludes sockets, lock files, +``probe/``, and the ``agent-backup-*`` import copies. Links and special +files fail, rather than enter the archive. **The archive holds +secrets**, including login tokens, the Telegram bot token, and the +WhatsApp link. Keep it private. There is no encryption or remote copy. + +Restore needs a stopped daemon and an empty destination. It checks the +token lock and validates the archive before it installs files, with +their modes. It rejects unsafe paths, links, and special files. A failed +restore can leave ``auth.lock`` in the destination. Use another empty +directory for a retry. Do not run the source and restored WhatsApp links +at the same time. Check the restored log and view before you use it in +place of the source. + +For a daily local archive with the last 14 kept, save this script as +``BACKUP_SCRIPT``. Replace ``BACKUP_DIR`` with a private archive +directory outside the data directory. Replace ``ONECHAT_BINARY`` with +the absolute path through the stable ``result-service/bin/onechat`` +package link. Make the archive directory with mode 0700 before you +enable the timer. + +.. code:: sh + + #!/bin/sh + set -eu + umask 077 + cd BACKUP_DIR + ONECHAT_BINARY backup "onechat-$(date +%F).tar.gz" + find . -maxdepth 1 -type f -name 'onechat-????-??-??.tar.gz' -printf '%f\n' | + sort -r | tail -n +15 | + while IFS= read -r file; do + rm -- "$file" + done + +Save these units as ``onechat-backup.service`` and +``onechat-backup.timer`` in the systemd user unit directory. Replace +``DATA_DIR`` and ``BACKUP_SCRIPT`` with absolute paths. The service uses +the daemon unit from User service above. + +.. code:: ini + + [Unit] + Description=Back up OneChat data + Requires=onechat.service + After=onechat.service + + [Service] + Type=oneshot + Environment="ONECHAT_DIR=DATA_DIR" + UMask=0077 + ExecStart=/bin/sh BACKUP_SCRIPT + +.. code:: ini + + [Unit] + Description=Back up OneChat each day + + [Timer] + OnCalendar=daily + Persistent=true + + [Install] + WantedBy=timers.target + +Enable the timer with the user manager. A failed backup leaves the +existing archives in place and skips removal of old archives. + +.. code:: console + + systemctl --user daemon-reload + systemctl --user enable --now onechat-backup.timer + systemctl --user list-timers onechat-backup.timer + ************ Daemon log ************ @@ -451,7 +579,8 @@ such as "remind me tomorrow at 9" or "every weekday at 8, tell me what my WhatsApp groups talked about". A schedule has a text, the task for the agent, and either one time or a cron expression. The agent also lists the schedules with their next times, and removes one when the user -asks. Only the agent has the schedule tools, not its subagents. +asks. The root and its children have the schedule tools, not their +subagents. Each schedule records its owner and wakes only that agent. A cron expression has five fields: minute, hour, day of month, month, and day of week, where 0 and 7 are Sunday. A field is a comma list of