X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/f226928c3a074ac4856ba07e8fd7107aba5444a3..723f6e18adc6482ed913e1618c8a76e981720c2b:/README.rst

diff --git a/README.rst b/README.rst
index 3112355..36db09c 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 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
 **************
@@ -236,14 +270,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
@@ -408,7 +443,8 @@ device. The terminal client and Telegram take three commands:
 
 ``/whatsapp status``
    Shows the link: not linked, linked and connected, or linked and
-   disconnected, with the times of the connection.
+   disconnected, with the times of the connection and the WhatsApp
+   routes.
 
 ``/whatsapp unlink``
    Ends the link and deletes the session. When WhatsApp is disconnected,
@@ -483,6 +519,13 @@ agent has the WhatsApp tools, not its subagents.
 Each batch of a group goes to the chat, also with no turn, and the
 memory tree summarizes it with model calls, which use the quota.
 
+The root manages source routes with ``route(source, agent)``,
+``unroute(source)``, and ``routes()``, only after the user agrees. A
+source is ``whatsapp:CHAT-ID``, with the ID from ``whatsapp_find`` or a
+``[WhatsApp]`` message, and the agent must be its child. The root keeps
+the map in ``agent/routes.json`` with mode 0600. Children and subagents
+have no route tools. There is no command to change routes.
+
 When the session holds a linked device, the daemon connects at its
 start. If the first connection fails, it tries again after 2 seconds,
 then doubles the wait up to 5 minutes. The inbox and commands stay
@@ -544,7 +587,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