Preserve queued agent mail across session eviction (#50087)

## Why

Unread queue-only messages prevented idle agents from unloading, and sending a
message to an evicted agent reloaded its session. Pending mail should not require
an idle recipient to occupy a loaded thread slot.

## What changed

- Retain queue-only mail in an in-memory runtime mailbox when a session unloads.
  Queue new messages for locally evicted agents without reloading them or
  starting a turn.
- Add `AgentControl::take_mailbox` and `AgentControl::watch_mailbox` so sessions
  can consume retained mail and react to host mailbox notifications.
- Preserve message order across eviction, reload, and subsequent follow-ups.
  Keep agents with outstanding durable sleep or turn-triggering mail loaded,
  and discard retained mail when an agent is removed or its tree shuts down.

## Testing

Add integration coverage for retaining mail across eviction, sending while
unloaded, and ordering messages around a follow-up after reload. Add a host
controller test verifying that mailbox notifications wake `wait_agent` and
that the message is delivered exactly once.

GitOrigin-RevId: 4b55647f9ee9d1aaf3753f0688863bda81617327
This commit is contained in:
jif
2026-10-01 20:17:34 +00:00
committed by copyberry
parent 26a49b3882
commit 960e878df4
14 changed files with 573 additions and 23 deletions
@@ -109,6 +109,7 @@ pub(crate) struct LocalAgentRuntime {
Arc<OnceLock<Arc<dyn ThreadInstructionsProvider>>>,
pub(super) registry: Arc<AgentRegistry>,
pub(super) residency: Arc<V2Residency>,
pub(super) mailboxes: Arc<super::mailbox::Mailboxes>,
/// Shared by every session in this tree, including private delegates.
pub(crate) shutdown: CancellationToken,
shutdown_state: Arc<AgentTreeShutdownState>,
@@ -125,6 +126,7 @@ impl LocalAgentRuntime {
thread_id_generator,
registry: Arc::default(),
residency: Arc::default(),
mailboxes: Arc::default(),
shutdown: CancellationToken::new(),
shutdown_state: Arc::default(),
agent_execution_limiter: Arc::default(),
@@ -204,6 +206,7 @@ impl LocalAgentRuntime {
pub(crate) fn request_shutdown(&self) -> Arc<AgentTreeShutdownState> {
self.shutdown_state.members.close();
self.shutdown.cancel();
self.mailboxes.close();
Arc::clone(&self.shutdown_state)
}