// Package inbox 提供 Agent 间消息传递的邮箱抽象.
//
// 每个 Agent 持有自己的 Inbox, 其他 Agent 通过 Router 向其 Send 消息.
// Send 非阻塞 (丢失优于卡死), Recv 阻塞 (推送优于轮询), Poll 非阻塞 (紧急检查).
// 内存实现适用单进程; UDS 实现跨进程, 为 Agent Teams 多进程协作预留.
//
// # API Consumption Shapes
//
// The Inbox interface spans two Flyto API shapes (see `docs/api-reference.md`
// "API 消费形态 / API Consumption Patterns"):
//
//   - Send: form 3 (synchronous callback). Non-blocking from the sender's
//     perspective but a direct method call; router / Agent Teams pipeline
//     drops on a full queue rather than blocking.
//   - Recv / Poll: form 2 (pull). Consumer (the owning Agent) actively
//     reads pending messages; Recv blocks until a message arrives or the
//     context is cancelled, Poll returns immediately.
//
// API 消费形态:
//
// Inbox 接口跨越两种 Flyto API 形态 (见 `docs/api-reference.md` "API 消费
// 形态 / API Consumption Patterns"):
//
//   - Send: 形态三 (同步回调). 对发送方是非阻塞语义但仍是直接方法调用;
//     router / Agent Teams 管道在满队列时丢弃而不阻塞.
//   - Recv / Poll: 形态二 (调取 pull). 消费者 (持有 Inbox 的 Agent) 主动
//     读待处理消息; Recv 阻塞直到有消息到或 ctx 取消, Poll 立即返回.
package inbox