Documentation
¶
Overview ¶
Package mail provides messaging for agent communication via beads.
Index ¶
- Variables
- func PriorityToBeads(p Priority) int
- type BeadsMessage
- type Delivery
- type GroupType
- type Mailbox
- func (m *Mailbox) Append(msg *Message) error
- func (m *Mailbox) Archive(id string) error
- func (m *Mailbox) ArchivePath() string
- func (m *Mailbox) Count() (total, unread int, err error)
- func (m *Mailbox) Delete(id string) error
- func (m *Mailbox) Get(id string) (*Message, error)
- func (m *Mailbox) Identity() string
- func (m *Mailbox) List() ([]*Message, error)
- func (m *Mailbox) ListArchived() ([]*Message, error)
- func (m *Mailbox) ListByThread(threadID string) ([]*Message, error)
- func (m *Mailbox) ListUnread() ([]*Message, error)
- func (m *Mailbox) MarkRead(id string) error
- func (m *Mailbox) MarkUnread(id string) error
- func (m *Mailbox) Path() string
- func (m *Mailbox) PurgeArchive(olderThanDays int) (int, error)
- func (m *Mailbox) Search(opts SearchOptions) ([]*Message, error)
- type Message
- type MessageType
- type ParsedGroup
- type Priority
- type Router
- type SearchOptions
Constants ¶
This section is empty.
Variables ¶
var ( ErrMessageNotFound = errors.New("message not found") ErrEmptyInbox = errors.New("inbox is empty") )
Common errors
var ErrUnknownAnnounce = errors.New("unknown announce channel")
ErrUnknownAnnounce indicates an announce channel name was not found in configuration.
var ErrUnknownList = errors.New("unknown mailing list")
ErrUnknownList indicates a mailing list name was not found in configuration.
var ErrUnknownQueue = errors.New("unknown queue")
ErrUnknownQueue indicates a queue name was not found in configuration.
Functions ¶
func PriorityToBeads ¶
PriorityToBeads converts a GGT Priority to beads priority integer. Returns: 0=urgent, 1=high, 2=normal, 3=low
Types ¶
type BeadsMessage ¶
type BeadsMessage struct {
ID string `json:"id"`
Title string `json:"title"` // Subject
Description string `json:"description"` // Body
Assignee string `json:"assignee"` // To identity
Priority int `json:"priority"` // 0=urgent, 1=high, 2=normal, 3=low
Status string `json:"status"` // open=unread, closed=read
CreatedAt time.Time `json:"created_at"`
Labels []string `json:"labels"` // Metadata labels (from:X, thread:X, reply-to:X, msg-type:X, cc:X)
Pinned bool `json:"pinned,omitempty"`
Wisp bool `json:"wisp,omitempty"` // Ephemeral message (filtered from JSONL export)
// contains filtered or unexported fields
}
BeadsMessage represents a message as returned by bd list/show commands. Messages are beads issues with type=message and metadata stored in labels.
func (*BeadsMessage) GetCC ¶
func (bm *BeadsMessage) GetCC() []string
GetCC returns the parsed CC recipients.
func (*BeadsMessage) IsCCRecipient ¶
func (bm *BeadsMessage) IsCCRecipient(identity string) bool
IsCCRecipient checks if the given identity is in the CC list.
func (*BeadsMessage) ParseLabels ¶
func (bm *BeadsMessage) ParseLabels()
ParseLabels extracts metadata from the labels array.
func (*BeadsMessage) ToMessage ¶
func (bm *BeadsMessage) ToMessage() *Message
ToMessage converts a BeadsMessage to a GGT Message.
type Delivery ¶
type Delivery string
Delivery specifies how a message is delivered to the recipient.
const ( // DeliveryQueue creates the message in the mailbox for periodic checking. // This is the default delivery mode. Agent checks with `gt mail check`. DeliveryQueue Delivery = "queue" // DeliveryInterrupt injects a system-reminder directly into the agent's session. // Use for lifecycle events, URGENT priority, or stuck detection. DeliveryInterrupt Delivery = "interrupt" )
type GroupType ¶
type GroupType string
GroupType represents the type of group address.
const ( GroupTypeRig GroupType = "rig" // @rig/<rigname> - all agents in a rig GroupTypeTown GroupType = "town" // @town - all town-level agents GroupTypeRole GroupType = "role" // @witnesses, @dogs, etc. - all agents of a role GroupTypeRigRole GroupType = "rig-role" // @crew/<rigname>, @polecats/<rigname> - role in a rig GroupTypeOverseer GroupType = "overseer" // @overseer - human operator )
type Mailbox ¶
type Mailbox struct {
// contains filtered or unexported fields
}
Mailbox manages messages for an identity via beads.
func NewMailbox ¶
NewMailbox creates a mailbox for the given JSONL path (legacy mode). Used by crew workers that have local JSONL inboxes.
func NewMailboxBeads ¶
NewMailboxBeads creates a mailbox backed by beads.
func NewMailboxFromAddress ¶
NewMailboxFromAddress creates a beads-backed mailbox from a GGT address. Follows .beads/redirect for crew workers and polecats using shared beads.
func NewMailboxWithBeadsDir ¶
NewMailboxWithBeadsDir creates a mailbox with an explicit beads directory.
func (*Mailbox) Append ¶
Append adds a message to the mailbox (legacy mode only). For beads mode, use Router.Send() instead.
func (*Mailbox) ArchivePath ¶
ArchivePath returns the path to the archive file.
func (*Mailbox) ListArchived ¶
ListArchived returns all messages in the archive file.
func (*Mailbox) ListByThread ¶
ListByThread returns all messages in a given thread.
func (*Mailbox) ListUnread ¶
ListUnread returns unread (open) messages.
func (*Mailbox) MarkUnread ¶
MarkUnread marks a message as unread (reopens in beads).
func (*Mailbox) PurgeArchive ¶
PurgeArchive removes messages from the archive, optionally filtering by age. If olderThanDays is 0, removes all archived messages.
type Message ¶
type Message struct {
// ID is a unique message identifier (beads issue ID like "bd-abc123").
ID string `json:"id"`
// From is the sender address (e.g., "gastown/Toast" or "mayor/").
From string `json:"from"`
// To is the recipient address.
To string `json:"to"`
// Subject is a brief summary.
Subject string `json:"subject"`
// Body is the full message content.
Body string `json:"body"`
// Timestamp is when the message was sent.
Timestamp time.Time `json:"timestamp"`
// Read indicates if the message has been read (closed in beads).
Read bool `json:"read"`
// Priority is the message priority.
Priority Priority `json:"priority"`
// Type indicates the message type (task, scavenge, notification, reply).
Type MessageType `json:"type"`
// Delivery specifies how the message is delivered (queue or interrupt).
// Queue: agent checks periodically. Interrupt: inject into session.
Delivery Delivery `json:"delivery,omitempty"`
// ThreadID groups related messages into a conversation thread.
ThreadID string `json:"thread_id,omitempty"`
// ReplyTo is the ID of the message this is replying to.
ReplyTo string `json:"reply_to,omitempty"`
// Pinned marks the message as pinned (won't be auto-archived).
Pinned bool `json:"pinned,omitempty"`
// Wisp marks this as a transient message (stored in same DB but filtered from JSONL export).
// Wisp messages auto-cleanup on patrol squash.
Wisp bool `json:"wisp,omitempty"`
// CC contains addresses that should receive a copy of this message.
// CC'd recipients see the message in their inbox but are not the primary recipient.
CC []string `json:"cc,omitempty"`
}
Message represents a mail message between agents. This is the GGT-side representation; it gets translated to/from beads messages.
func NewMessage ¶
NewMessage creates a new message with a generated ID and thread ID.
func NewReplyMessage ¶
NewReplyMessage creates a reply message that inherits the thread from the original.
type MessageType ¶
type MessageType string
MessageType indicates the purpose of a message.
const ( // TypeTask indicates a message requiring action from the recipient. TypeTask MessageType = "task" // TypeScavenge indicates optional first-come-first-served work. TypeScavenge MessageType = "scavenge" // TypeNotification is an informational message (default). TypeNotification MessageType = "notification" // TypeReply is a response to another message. TypeReply MessageType = "reply" )
func ParseMessageType ¶
func ParseMessageType(s string) MessageType
ParseMessageType parses a message type string, returning TypeNotification for invalid values.
type ParsedGroup ¶
type ParsedGroup struct {
Type GroupType
RoleType string // witness, crew, polecat, dog, etc.
Rig string // rig name for rig-scoped groups
Original string // original @group string
}
ParsedGroup represents a parsed @group address.
type Priority ¶
type Priority string
Priority levels for messages.
const ( // PriorityLow is for non-urgent messages. PriorityLow Priority = "low" // PriorityNormal is the default priority. PriorityNormal Priority = "normal" // PriorityHigh indicates an important message. PriorityHigh Priority = "high" // PriorityUrgent indicates an urgent message requiring immediate attention. PriorityUrgent Priority = "urgent" )
func ParsePriority ¶
ParsePriority parses a priority string, returning PriorityNormal for invalid values.
func PriorityFromInt ¶
PriorityFromInt converts a beads-style integer priority to a Priority. Accepts: 0=urgent, 1=high, 2=normal, 3=low, 4=backlog (treated as low). Invalid values default to PriorityNormal.
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router handles message delivery via beads. It routes messages to the correct beads database based on address: - Town-level (mayor/, deacon/) -> {townRoot}/.beads - Rig-level (rig/polecat) -> {townRoot}/{rig}/.beads
func NewRouter ¶
NewRouter creates a new mail router. workDir should be a directory containing a .beads database. The town root is auto-detected from workDir if possible.
func NewRouterWithTownRoot ¶
NewRouterWithTownRoot creates a router with an explicit town root.
func (*Router) ExpandListAddress ¶
ExpandListAddress expands a list:name address to its recipients. Returns ErrUnknownList if the list is not found. This is exported for use by commands that want to show fan-out details.
func (*Router) GetMailbox ¶
GetMailbox returns a Mailbox for the given address. Routes to the correct beads database based on the address.
func (*Router) ResolveGroupAddress ¶
ResolveGroupAddress resolves a @group address to individual recipient addresses. Returns the list of resolved addresses and any error. This is the public entry point for group resolution.
func (*Router) Send ¶
Send delivers a message via beads message. Routes the message to the correct beads database based on recipient address. Supports fan-out for: - Mailing lists (list:name) - fans out to all list members - @group addresses - resolves and fans out to matching agents Supports single-copy delivery for: - Queues (queue:name) - stores single message for worker claiming - Announces (announce:name) - bulletin board, no claiming, retention-limited