Deliver messages between parent and child agents

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index 31123553aa64aed167b6b818276448a291e6538f..b60f984379791785347d2cdfea98ad15da77dc0f 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -138,6 +138,33 @@ 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. Create its directory and ``config.json`` by hand
+before startup. Use the root config fields with a separate random ID,
+set ``name`` to ``NAME``, and add ``parent`` with the root name and
+``responsibility`` with the child's area. The daemon opens all children
+at startup. A missing or invalid child config stops startup. Only one
+level of children is supported.
+
+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. No tools send messages
+between parent and child agents yet.
+
 **************
  User service
 **************
@@ -236,14 +263,15 @@ command prints its path and size in bytes. With no daemon, it fails.
    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 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.
+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, Telegram offset, tokens,
-and WhatsApp state and session. It excludes sockets, lock files,
+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