mailbox

type Mailbox interface {
	// Send delivers a message to the recipient's inbox.
	// For KindBroadcast, ToAgent must be "*" and TeamID must be set;
	// the implementation expands it to all agents in that team.
	Send(ctx context.Context, msg Message) error

	// Receive returns all unread messages for agentID, oldest first.
	Receive(ctx context.Context, agentID string) ([]Message, error)

	// MarkRead marks a single message as read.
	MarkRead(ctx context.Context, msgID string) error

	// MarkAllRead marks all unread messages for agentID as read.
	MarkAllRead(ctx context.Context, agentID string) error

	// History returns up to limit messages for agentID (read and unread),
	// newest first.
	History(ctx context.Context, agentID string, limit int) ([]Message, error)

	// Thread returns all messages in a conversation thread rooted at rootID.
	Thread(ctx context.Context, rootID string) ([]Message, error)

	// Delete removes a message permanently.
	Delete(ctx context.Context, msgID string) error

	// PendingCounts returns the number of unread messages per agent for the
	// given agent IDs. Agents with zero unread messages are absent from the
	// returned map (treat missing keys as 0). Used by Dispatcher to route
	// tasks to the least-loaded available agent.
	PendingCounts(ctx context.Context, agentIDs []string) (map[string]int, error)
}

type Message struct {
	// ID is a UUID generated at send time.
	ID string `json:"id"`

	// Kind classifies the message intent.
	Kind MessageKind `json:"kind"`

	// FromAgent is the sender's agent UUID (or "system" for engine events).
	FromAgent string `json:"from_agent"`

	// ToAgent is the recipient's agent UUID.
	// For broadcast messages this is the expanded individual recipient.
	ToAgent string `json:"to_agent"`

	// Subject is a short one-line summary of the message.
	Subject string `json:"subject"`

	// Body is the full message content (plain text or markdown).
	Body string `json:"body"`

	// ReplyTo is the ID of the parent message when Kind == KindReply.
	ReplyTo string `json:"reply_to,omitempty"`

	// TeamID scopes the message to a team (optional).
	TeamID string `json:"team_id,omitempty"`

	CreatedAt time.Time  `json:"created_at"`
	ReadAt    *time.Time `json:"read_at,omitempty"`
}

type MessageKind string

type SQLiteMailbox struct {
	// contains filtered or unexported fields
}