Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(messaging): document operator decision requests

Gabriel Alencar0f65e1b5f8da
diff --git a/docs/agent-messaging.md b/docs/agent-messaging.md
index 17a452b6..f2c85247 100644
--- a/docs/agent-messaging.md
+++ b/docs/agent-messaging.md
@@ -137,6 +137,156 @@ is a bounded, best-effort signal, not a durable queue, processing acknowledgment
or automatic agent wakeup. Consumers still need their own deduplication and
recovery policy. This does not add a notification for raw Stop observations.
+## Operator decisions, by subject and body
+
+An orchestrator that must stop for a person (accept a test exception, pick a
+design, confirm a merge) uses this same mailbox. The server already stores an
+optional one-line `subject` and a `body` on every message. This section is the
+convention both sides share so a companion and every orchestrator encode a
+decision the same way. The tools stay `memory_message_send` and
+`memory_message_list`. [#1281](https://github.com/akitaonrails/ai-memory/issues/1281)
+
+The server stores that text as opaque message content. Correlation, options,
+and who may answer live in the text plus the provenance the list already
+returns. A reply is an ordinary send back to the project that asked.
+
+### Asking
+
+Send the question to the project where the operator, or the companion that
+serves them, reads mail. That project is an ordinary one: it must already
+exist, and the send needs write on it, the same as any other message. Agree on
+the coordinate out of band (for example `default/operator`). The server has no
+separate operator-mailbox flag.
+
+`memory_message_send`:
+
+- `to_workspace` and `to_project`: that mailbox.
+- `from_workspace` and `from_project`: the project that should receive the
+ answer. Static clients name these; a guessed sender is refused, so the
+ reply has a real return address.
+- `subject`: `decision: <short question>`, one line, within 200 characters.
+ The inbox listing and `/web` show this line. `decision-reply:` does not
+ share the prefix, so a reply never matches a question filter.
+- `body`: the question, the options, and the project the answer goes back to.
+ Compose it as a complete prompt. The recipient has no other context. Keep
+ it within 8,000 characters; a longer body is truncated on send. Secrets are
+ scrubbed on the way in.
+
+The call returns `message_id`. Keep it. The reply names that id.
+
+```
+question: Accept the known-flake exception on the export test?
+requires_root: false
+reply_project: default/orchestrator
+options:
+- id: accept
+ label: Accept the exception
+ description: Land the change with the flake written down.
+ recommended: true
+- id: reject
+ label: Send it back
+ description: The test has to be stable first.
+details: Failed once in forty CI runs. The flake is timed in the export suite.
+links:
+- https://example.test/pull/12
+```
+
+`reply_project` is `workspace/project` of the asker, the same names passed as
+`from_workspace` and `from_project`. The answerer sends there. The option
+`id` values are the asker's. The asker keeps, locally, the action each id
+maps to, and the message carries the labels a person chooses from.
+
+`requires_root: true` marks a risky decision (merge, deploy, delete) for the
+companion and the asker. Write access is the server's rule: posting the
+question needs write on the mailbox project, and posting the reply needs write
+on the asking project ([per-project grants](design-per-project-authz.md)).
+The companion refuses to send a risky answer unless the caller is root, and
+the asker acts on a reply only when `from_owner_user` is a root credential.
+See [users](users.md).
+
+The same text works from the terminal:
+
+```
+ai-memory message send --to-workspace default --to-project operator \
+ --from-workspace default --from-project orchestrator \
+ --subject "decision: Accept the known-flake exception?" \
+ "$(cat <<'EOF'
+question: Accept the known-flake exception on the export test?
+requires_root: false
+reply_project: default/orchestrator
+options:
+- id: accept
+ label: Accept the exception
+ description: Land the change with the flake written down.
+ recommended: true
+- id: reject
+ label: Send it back
+ description: The test has to be stable first.
+EOF
+)"
+```
+
+### Answering
+
+List the mailbox with `memory_message_list` (`box` `inbox`) and read pending
+rows whose subject starts with `decision: `. `/web` shows the same rows
+(subject, sender, a 160-character snippet) and leaves them pending. Reading
+stays a list. Popping the question would claim it, so other readers would no
+longer see it.
+
+The answer is `memory_message_send` to `reply_project`:
+
+- `subject`: `decision-reply: <message_id>`, exact, with the question's `id`
+ from the list. The id is a UUID, so the subject stays inside 200 characters.
+- `body`: the chosen option id, then any free text.
+
+```
+question_id: 018f1a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b
+option: accept
+comment: Accepting the exception; the flake is already written down.
+```
+
+`comment` is untrusted input, the same as any popped body. The asker weighs it
+with the user. It does not authorize a command on its own.
+
+A companion serves the page (open questions, options, answer buttons, the
+audit trail) and calls only the public MCP or admin message routes. The
+built-in `/web` mailbox stays read-only. See
+[companion crates](companion-crates.md).
+
+### How the asker sees the answer
+
+Poll `memory_message_list` on the asking project's inbox. Take the oldest
+pending row whose subject is exactly `decision-reply: ` plus the saved
+`message_id`. List is oldest-first and returns pending rows only, at most
+`limit` of them (default 50, maximum 200), with no offset. A reply that sits
+behind more than `limit` older pending rows is outside that page, so keep this
+inbox drained: pop mail you have finished with, and cancel questions you have
+given up on. A project used only for these replies stays inside the window.
+
+Each row includes `id`, `subject`, `body`, `state` (`pending`),
+`from_owner_user`, `from_workspace_id`, `from_project_id`, and `from_agent`.
+Judge who answered from `from_owner_user` (the sender credential, when the
+call authenticated as a user) and from the sender project. A message sent
+through MCP or `ai-memory message send` records `from_agent` as `other`; the
+credential and the sender project are the provenance.
+
+Pop that reply with its `message_id` when you accept it. A pop claims it
+once. Leave it listed until then so a retry still sees it. Then
+`memory_message_cancel` the question, so the mailbox drops the stale ask.
+Cancelling the question leaves the reply where it is: the reply was sent by
+the answerer and sits in the asker's inbox.
+
+Further replies to the same id can still arrive. The convention is that the
+oldest pending match is the answer; pop or leave the rest as ordinary mail.
+The server accepts every send that has write on the destination.
+
+The poll is the caller's own loop, with its own backoff. An observer webhook
+on `message_send` can wake a companion: the notification carries the recipient
+scope and the actor, and the companion then lists that inbox. It is the
+best-effort signal described above, not a queue and not a wakeup for the
+orchestrator. Each inbox still holds at most 256 pending messages.
+
## In the web UI
The `/web` UI is read-only here too. A project card shows an amber `N inbox`
diff --git a/docs/cookbook.md b/docs/cookbook.md
index e74f0f99..1fe45d68 100644
--- a/docs/cookbook.md
+++ b/docs/cookbook.md
@@ -299,6 +299,37 @@ compacted or merged stays in git and the supersession chain, recoverable with
add the export endpoint" (`memory_message_send`), and over there "check my
inbox" (`memory_message_pop`). See [`agent-messaging.md`](agent-messaging.md).
+## Recipe: ask an operator to decide
+
+When an orchestrator has to stop for a person, send a normal cross-project
+message and poll for a normal reply. The subject lines are the shared
+convention; `memory_message_send` and `memory_message_list` are the tools.
+
+1. Send to the project the operator reads. `subject` is
+ `decision: <short question>`. The body names the question, each option's
+ `id` and label, and `reply_project: <your workspace>/<your project>`.
+ Save the returned `message_id`. You need write on that mailbox project,
+ and it must already exist.
+2. The operator, or a companion, answers with `memory_message_send` back to
+ `reply_project`. `subject` is `decision-reply: <message_id>`. The body
+ carries `option: <id>`. Sending the reply needs write on your project.
+3. Poll `memory_message_list` on your inbox until a pending row's subject is
+ that exact `decision-reply:` line. The oldest match is the answer. Pop it
+ when you take it, then `memory_message_cancel` the question.
+
+Read `from_owner_user` on the reply before you act. A body line
+`requires_root: true` tells the companion to send that reply only for a root
+caller, and tells you to act only when the credential is root. `/web` shows
+the mailbox and leaves every message pending.
+
+The list is oldest-first, 50 rows by default and 200 at most, so keep the
+inbox you poll from drained. A companion can wake on the `message_send`
+observer webhook, then list; the webhook carries scope and actor, and the
+orchestrator still polls.
+
+Full layout and limits:
+[`agent-messaging.md`](agent-messaging.md#operator-decisions-by-subject-and-body).
+
## Recipe: several accounts or an external launcher
Give each account or provider its own config home and pass it with `--env`, so