design: messaging primitives beyond basic mail #20
Description
Summary
Gas City has basic point-to-point mail (gc mail send/check/inbox), but gastown has a richer messaging infrastructure that we don't yet have equivalents for. Before implementing anything, we need to figure out which messaging primitives actually belong in the SDK vs which are pack-level concerns.
What gastown has that we don't
- Mailing lists — broadcast to named groups (e.g.,
crew/,all/) - Work queues — bead-backed queues that agents pull from (beyond
bd ready) - Announce channels — one-to-many broadcast for system events
- Nudge channels — targeted wakeup signals with message payloads
- Channel subscriptions — agents subscribe to topics of interest
What Gas City has today
gc mail send <target> -s <subject> -m <body>— point-to-point mail via beadsgc mail check --inject— check inbox and inject into sessiongc mail inbox— list messages- Nudge via
AgentProtocol.SendPrompt()— fire-and-forget text injection
Open questions
- Which of these are SDK primitives vs pack config? Mailing lists could just be a prompt convention ("send to each of: X, Y, Z") rather than infrastructure.
- Is broadcast a primitive?
gc mail send --broadcastor a separategc announce? Or is it just N individual sends? - Do we need channels/topics? Or is label-based bead query (
bd list --label=channel:announce) sufficient? - Nudge vs mail distinction — nudge is ephemeral (lost if agent is down), mail is persistent (bead-backed). Is this the right split? Do we need "persistent nudge" (queued delivery at idle boundary)?
- Relationship to async-nudge-delivery design —
docs/design/async-nudge-delivery.mdalready explores queued nudge delivery. How does that interact with messaging?
Desired outcome
A design doc that identifies the minimal set of messaging primitives Gas City needs, with clear rationale for what's SDK infrastructure vs what's pack-level convention. Should follow the Primitive Test (Atomicity + Bitter Lesson + ZFC).
References
- Gas City feature parity audit: item 2.5
- Existing design:
docs/design/async-nudge-delivery.md - Current mail impl:
internal/mail/