Agent-to-operator decision requests on top of cross-project messaging: in scope? #1281

Problem this would solve

I run several coding agents at the same time, each in its own worktree. An orchestrator agent coordinates them. The agents often stop on a decision that only a human can make: accept a test exception, pick a design option, confirm a merge.

Today each orchestrator makes its own channel for these questions: terminal text, a local file, or a local web page. This causes four problems:

• The human must watch every terminal or page.
• The answer has no provenance. The orchestrator cannot tell who answered, or through which credential.
• A collaborator cannot answer without access to the machine.
• An orchestrator that waits for an answer polls a file, and its watch expires.

ai-memory already has most of the parts that a fix needs: cross-project messaging with a claim-once queue, sender provenance, fenced untrusted bodies, users with aim_ keys, per-project grants (#708), an audit log, and observer webhooks. Messaging today is agent to agent. A decision request is agent to operator, with a reply that goes back to the agent that asked.

What a prototype showed

For one session, I built a throwaway version outside ai-memory. Two worker agents and two reviewer agents worked on two GitHub issues. The orchestrator posted 7 questions with 2 options each. A collaborator answered all 7 in about 3 minutes through a scoped link. The lessons:

• A question with declared options is the right unit. Each option maps to one action that the orchestrator wrote in advance.
• Provenance (who answered, with which key) decides how much the orchestrator trusts an answer.
• Free text needs the same fence as a popped message.
• A risky decision (merge, deploy, delete) must accept an answer only from root, even when a collaborator can answer the other questions.
• The orchestrator needs a durable wait and a delivery acknowledgement. My file watch expired every 30 minutes, and one send failed with no visible error.

Proposed solution

Add small primitives to messaging. Keep the answering UI out of core, as a companion (docs/companion-crates.md).

1. A decision message kind. Structured fields: question, options (each with label, description and recommended), details, links, and requires_root.
2. A reply that names its question. memory_message_send gets reply_to. The reply lands in the inbox of the project that asked, fenced and with provenance, like any message. A question takes one reply. The first reply wins.
3. An operator mailbox. One opt-in project per workspace receives decision requests. Per-project grants decide who can read it and answer. If requires_root is set, the server refuses a reply from a non-root caller.
4. A wait. memory_message_wait, or a long-poll option on memory_message_list, returns when a reply to a given message arrives, or when a timeout ends.
5. Notifications with no core change. Observer webhooks already fire on message_send. A companion uses them to send a Telegram message or a Web Push notification.

A companion then serves the page: the open decisions, their options, answer buttons and the audit trail. It calls only the public HTTP and MCP surfaces.

Alternatives considered

1. No core change. A companion encodes the options and the reply link in the message body by convention, and agents poll memory_message_list. This works, but every orchestrator must know the convention, the server cannot enforce requires_root, and every agent polls.
2. A /web page that answers decisions. I do not ask for this. docs/agent-messaging.md says that consuming a message stays an agent action, and ai-memory-web is read-only by contract.
3. A separate service. It duplicates the users, keys, grants, audit log and messaging that ai-memory already has. Each agent then needs a second MCP server.

Would this break existing installs?

No, if the new fields are optional and the operator mailbox is opt-in. The new message columns need a migration. Existing messages and tools keep their behaviour.

Question

Is this in scope for ai-memory? If yes, which shape do you prefer?

1. The core primitives above, with the UI as a companion. This is my recommendation.
2. No core change, and a documented companion pattern on top of the current messaging.

If decision requests are a separate product, as the browser wiki editor was in #482, I will keep this outside ai-memory.

Additional context

• docs/agent-messaging.md: the claim-once queue, provenance, and the read-only /web mailbox.
• docs/companion-crates.md: the boundary for UI around ai-memory.
• docs/design-per-project-authz.md (Multi-user servers have no per-project authorization #708): grants for a shared server.
• Web UI: any design or appetite for a write surface (edit-from-browser)? #482 and Web UI to triage pending auto-improve writes (approve/reject only) — PR welcome? #855: the earlier discussions about browser write surfaces.