Platform providers
Gopala’s agents take work from Lupyd, Slack and Discord through providers; this page compares them and shows how each maps chats, mentions and members.
Each provider implements one neutral contract, the gopala_platform::Platform trait, so
everything above it works the same on every platform. Three ship with Gopala:
| Provider | Built on | A conversation is | Channels | Message ids |
|---|---|---|---|---|
| Lupyd | firefly-mcp / firefly-client (MLS) | a Lupyd group, or a direct chat | the group’s channels (numbers as strings) | Firefly server time, µs |
| Slack | slack-morphism, Socket Mode + Web API | one Slack channel (public, private or group DM), or an IM | none (channel_id is always None) |
the message ts in µs |
| Discord | twilight 0.18 (gateway, HTTP, in-memory cache) | one server (guild), or a DM | the server’s text channels and threads | snowflakes |
This page describes the contract and what each provider does with it. Setting the bots up is in operations.md.
What a provider does
Section titled “What a provider does”flowchart LR
PL[(the platform's API)] <--> PR["provider<br/>impl Platform"]
PR -- "Event (mpsc)" --> R["Router"]
R -- "meta, admit_direct, leave, joined" --> PR
HC["HostConversation"] -- "send, edit, delete, react,<br/>message, history, search, meta" --> PR
R --> HC
A provider signs in with credentials from environment variables named in its config section,
turns the platform’s traffic into neutral Events on the channel run is given, and carries out
actions in one conversation at a time when the manager asks. Policy, commands, approvals,
sessions, VMs, MCP tools, watching, budgets and metering all live above the trait and work the
same on every platform.
Conventions
Section titled “Conventions”- Message ids are
u64and unique within a conversation. Slack’sts("1714053600.123456") maps losslessly to microseconds (gopala_slack::text::ts_to_id). - Channels (sub-rooms of a conversation) are opaque strings (
Option<String>). - Usernames are the platform’s stable handle for a person, the same kind of string as
Platform::bot. Policy allowlists, approvers and watch tokens use them. Slack uses the person’s lowercasenamehandle (or the user id when there is none); Discord the lowercase unique username. - A provider’s name (
Platform::name) is[a-z0-9]{1,16}, used in conversation ids, keys and[platforms.<name>].
Identifying conversations
Section titled “Identifying conversations”pub struct ConversationId { pub platform: String, // the provider's name, e.g. "slack" pub kind: Kind, // Kind::Group or Kind::Direct pub id: String, // the platform's group id, or the peer's username for a direct chat}Build them with ConversationId::group(name, id) and ConversationId::direct(name, username).
ConversationId::key() derives the key that names the conversation’s VM directory, journal scope,
watch room and budget entry:
| Conversation | Key |
|---|---|
group, id is ≤ 24 lowercase ASCII letters/digits (Lupyd 42, Discord snowflakes) |
<platform>-g-<id> (e.g. lupyd-g-42) |
group, any other id (e.g. Slack C024BE91L) |
<platform>-g-<16 hex of SHA-256(id)> |
| direct chat | <platform>-d-<16 hex of SHA-256(ASCII-lowercased username)> |
Keys are filesystem- and URL-safe ([a-z0-9-]{1,48}), stable across restarts, never contain
usernames, and differ between platforms and between groups and direct chats. Keep ids stable: a
different id string for the same group is a different conversation, with a new VM disk and an
empty journal.
Events
Section titled “Events”Platform::run(self: Arc<Self>, events: mpsc::Sender<Event>) delivers events until the platform
stops or the receiver is gone (return Ok(()) when send fails). All providers share one channel
(capacity 1024) read by the router loop.
Event |
When | What the manager does (Router::handle) |
|---|---|---|
Message(Incoming) |
someone else posted, edited, deleted or reacted where the bot is | admission (DM policy), records it for wait_for_events, approvals, commands, wake-up rules, delivery to the agent |
Joined { conversation } |
the bot was added to a group | check_invite: leaves via Platform::leave if behavior.invites doesn’t allow the group’s owner |
MembersChanged { conversation, joined, left } |
people joined or left a group | revokes watch tokens of everyone in left; if the bot itself left, closes the conversation; else refreshes meta and records the change |
Updated { conversation } |
name, channels or roles changed | refreshes meta, records the change |
Fatal { reason } |
the provider can’t go on | Gopala stops with reason as the error |
If run returns an error, daemon::run turns it into Event::Fatal { reason: "<name>: <error>" }.
Don’t send events for the bot’s own messages, and skip content kinds the manager doesn’t model.
What raises Fatal: Lupyd’s sign-out or device removal; Slack’s invalid_auth,
account_inactive or token_revoked from any call, the app being uninstalled, or a failed token
check (both tokens are rechecked every ten minutes); Discord’s gateway closing with an
authentication or intents error (4004, 4013, 4014 and similar, with a message saying what to turn
on).
Incoming
Section titled “Incoming”pub struct Incoming { pub conversation: ConversationId, pub channel_id: Option<String>, // None in direct chats (and always on Slack) pub from: String, // the sender's username pub message_id: u64, pub at: String, // RFC 3339, UTC pub content: Content, // Message{text, reply_to, files} | Edit{of, text} | Delete{of} | Reaction{to, emoji} pub mentions_bot: bool, pub addressed_text: String, pub from_agent: bool, // sent by another agent (see "Other agents")}Mention syntax is the provider’s business, so it fills in two fields:
mentions_bot: the message mentions the bot. Lupyd:@usernameas a whole, case-insensitive word (gopala_lupyd::mentions). Slack:<@U…>with the bot’s user id. Discord:<@id>or<@!id>for the bot, or<@&role>for one of the bot’s roles in that server. Withrespond_to = "mentions"this is what wakes the agent in groups.addressed_text: the text with a leading mention of the bot removed (plus the,/:and spaces after it), forContent::Message; empty for other content. Commands (/watch,/status,/stop,/help,/listen) and approval replies (yes,2) are parsed from it, so@bot /statusand@bot yeswork.
The agent still gets the full text. Slack renders its <@U…> markup as @username; Discord
passes the message content as Discord sends it (<@id> included). Content::Reaction with an
empty emoji means the reaction was taken back. files is a count; file contents aren’t
available to agents.
Messages from other agents (from_agent) pass only when they mention the bot or reply to one of
its messages; the provider drops the rest, and the host drops them all when [collaboration] is
off. See Other agents. The bot’s own messages never come through.
The trait, method by method
Section titled “The trait, method by method”| Method | Contract | Lupyd | Slack | Discord |
|---|---|---|---|---|
name |
Provider name, [a-z0-9]{1,16}; matches every ConversationId it produces and its config section |
lupyd |
slack |
discord |
bot |
The bot’s own username; used for reply-to-bot detection, own-message checks, the system prompt and leave detection | the account’s username | the bot user’s lowercase name (auth.test) |
the bot’s lowercase username |
run |
See Events; spawned once by daemon::run |
polls firefly-mcp’s event log | Socket Mode listener (no public URL), redeliveries dropped by event id, token check every 10 min | one gateway shard (up to 2500 servers) |
meta |
Meta{title, description, channels, members, owner}; owner drives invites and approvers = "owner"; None when unknown |
group extension, local group info | channel name, purpose, creator as owner, members (up to 1000) | server name, owner, readable text channels and threads, members (needs the Server Members intent) |
send |
Send a message; channel: None means the default. The manager has already split long text and applied the rate limit. Ordinary messages must not notify more than the platform does for a normal message (no @everyone, no role pings) |
channel number, or the first channel | markdown_text up to 12,000 characters, escaped mrkdwn text beyond; a reply goes into the parent’s thread |
splits again at 2000 characters; mentions can ping users but not @everyone, @here or roles |
send_notifying |
Send a message that notifies an Audience; see below. Default: Audience::plain_prefix in front of send |
@everyone/@here as text, @username checked against the members, roles skipped |
<!channel>, <!here>, <!subteam^ID> (from usergroups.list), <@U…>, in a mrkdwn block |
@everyone, @here, <@&role>, <@id>, with allowed_mentions set to exactly those |
edit / delete |
A message the bot sent; the manager checks ownership first (HostConversation::check_own) |
in the original’s channel | chat.update / chat.delete |
refuses edits over 2000 characters |
react |
Empty emoji removes the bot’s reaction; approval seeds use ✅ ❌ 1️⃣…🔟 | Unicode ⇄ Slack names (:name: when there is no match) |
Unicode or custom emoji | |
message |
One message as it reads now, or None |
stores, folded | conversations.history / replies lookup |
REST, or the recent-message cache |
history |
Up to limit messages before before, oldest first; backs read_messages |
reads 3 × limit rows and folds edits/reactions |
the channel’s own messages (not thread replies); refuses a channel_id |
one channel, or the default one |
search |
Search confined to this conversation; backs search_messages |
Firefly’s local full-text index | scans the newest 1000 messages (bots can’t call search.messages) |
scans 200 messages in each of up to 25 channels |
admit_direct |
Accept or decline DMs from user where the platform has message requests; see below |
set_user_accepted |
no-op (the router still drops refused senders) | no-op |
leave |
Leave a group | leave_group |
conversations.leave (a DM can’t be left) |
leaves the server |
joined |
Groups the bot is in now, for re-applying the invite policy at startup | local groups with state | users.conversations (public, private, group DMs) |
the servers seen at connect and since |
shutdown |
Stop cleanly (default: nothing) | disposes the Firefly client | stops the listener | closes the gateway |
replies_are_threads |
Whether a reply is a place (a thread) rather than a quote; when true, every part of a long message the host splits goes to reply_to, not just the first (HostConversation::send). Default false |
false |
true |
false |
member |
Is this person in the group now, with which roles and permissions; see below. Default Ok(None): nobody, so only the operator can monitor |
group role, its permission bits by name, group owner | user-group handles, workspace admin/owner/primary_owner, channel creator |
role names, server permissions (lowercase flag names), server owner |
agents |
The other agents in a group, for list_agents; see below. Default: none |
holders of the agent group role, bios from the Lupyd API | bot users and members of the agent user group, profile title and status | bots and holders of the agent role, no bio |
Every conversation passed to these methods belongs to this provider (the router looks providers
up by ConversationId::platform). Errors are anyhow::Result; agent-facing ones reach the agent
as tool errors, so keep them short (“Slack conversations have no channels; leave channel_id out”).
Notifying people
Section titled “Notifying people”Platform::send_notifying(conversation, channel, text, reply_to, audience) sends one message
that notifies audience (gopala_platform::Audience). The host calls it for the first part of a
warning or critical message and for host events, and only when [alerts] gives the
conversation a non-empty audience and its hourly cap allows; direct chats never get here. The
contract:
Audience { everyone, here, roles, users }is neutral: roles and users are names as people see them (a Slack user group handle, a Discord role name, a username), never platform ids or mention syntax. Render them in the platform’s own syntax in front of the text (gopala_platform::prefixed).- Let exactly those mentions notify, and nothing else in the text. Discord does this with
allowed_mentions; Slack puts the mentions in a mrkdwn block so the agent’s markdown can’t add any. - A name the platform doesn’t know (or a kind it can’t mention, like roles on Lupyd) is skipped
with a
log::warn!, and the message still goes out. Never fail the send because of the audience; fail only when sending itself fails. heremeans “people who are online” where the platform tells them apart; elsewhere render it as readably as you can.- Return the id of the first message, as
senddoes.
The default implementation names the audience in plain text (@everyone @here @ops @alice) and
calls send, which is right for a platform without notifying mentions.
Membership for monitoring
Section titled “Membership for monitoring”Platform::member(conversation, user) -> anyhow::Result<Option<Member>> decides who may follow a
group’s agent on /monitor, /api/monitor/ and /watch (see
architecture.md). The host asks it for groups only (in a direct
chat the peer is the only member), caches the answer per (key, username) for
monitoring.membership_cache_secs, and drops it on MembersChanged, Updated and the bot
leaving. The contract:
Ok(None)whenuserisn’t in the conversation now, or isn’t known. Deactivated or departed accounts are nobody.Ok(Some(Member { roles, permissions, owner }))otherwise.rolesare role names as people see them, the namesrole:rules use (and, on Slack and Discord, alerts).permissionsare the platform’s own permission names in lowercase snake_case, aspermission:rules name them.owneris the person who owns the group (the same oneMeta.ownerreports).useris spelled as the platform spells usernames inIncoming.from; match it exactly as your platform does (the host caches case-sensitively).Erronly when the platform couldn’t be asked. The host logs it, treats the person as not a member and doesn’t cache it, so the next request asks again.- Report membership changes as events (
MembersChangedwith who joined and left,Updatedfor role or permission changes) so access ends without waiting for the cache. Keep any cache of your own short.
What the three providers answer:
| Member if | roles |
permissions |
owner |
|
|---|---|---|---|---|
| Lupyd | in this device’s copy of the group (its Firefly extension with the MLS roster) | the member’s group role | that role’s permission bits: see_message, pin_message, add_message, manage_channel, manage_role, manage_member, manage_group |
the group owner |
| Slack | listed by conversations.members (cached 30 s, or until someone joins or leaves) and not deactivated (users.info) |
handles of their user groups (cached 5 min; none without usergroups:read) |
admin, owner, primary_owner from users.info |
the channel’s creator |
| Discord | a server member, from the cache (current with the Server Members intent) or a REST member search | their role names | server-level permissions from @everyone and their roles, as lowercase twilight flag names; administrators and the owner get every permission |
the server owner |
Other agents
Section titled “Other agents”Groups can hold several agents (see architecture.md). Two pieces
of the trait carry that, and both use the role named collaboration.agent_role (default agent)
to mark agents that aren’t bot accounts:
Incoming.from_agent: set when the sender is another agent, a bot account or someone holding the agent role. Pass such a message on only when it mentions the bot or replies to one of the bot’s messages; drop the rest. The host then lets it wake the agent only under[collaboration], never runs it as a command or an approval answer, and caps it per hour.Platform::agents(conversation, agent_role) -> anyhow::Result<Vec<Peer>>: the other agents in a group, behind thelist_agentstool. Never include the bot itself; return nothing for a direct chat; sort by username and return at most 50.Peer { username, display_name, about, roles, bot }:usernameis what to @mention (spelled as inIncoming.from),display_nameonly when it differs,aboutwhat they say they do (plain text, trimmed, at most 2000 characters),rolestheir role names in this group,botfor bot accounts. The host passes the currentagent_roleon every call and caches the answer per conversation for 5 minutes, dropping it onMembersChangedandUpdated. A platform error reaches the agent as “couldn’t list agents:”, so keep messages short. The default implementation returns no agents.
Each provider also has an inherent set_agent_role(&self, String), which main::run calls once
after connecting with collaboration.agent_role; from_agent uses that copy, so a changed role
reaches it at the next restart (until then each uses the default agent). Lupyd compares role
names ignoring case; Slack strips a leading @ and lowercases the handle.
| Lupyd | Slack | Discord | |
|---|---|---|---|
| Counts as an agent | a member whose group role is the agent role (Lupyd has no bot accounts) | bot users, plus members of the user group whose handle is the agent role; never Slackbot or deactivated accounts | bot members, plus members holding a role named like the agent role |
about |
the member’s profile bio from GET {platforms.lupyd.profile_api_url}/user?users=a,b (one request, with the bot’s Lupyd access token; a lupyd.user.Users answer whose bios are encoded PostBodys, shown as their plain text or markdown; element bodies give none, as in the Lupyd app). If the request fails, the list still comes back without bios and the log says lupyd: can't read the profiles of … |
the profile title plus status, e.g. “Reviews pull requests (status: reviewing #42)” | none: one bot can’t read another’s application description |
display_name, roles |
none; the group role | none; the person’s user group handles | nickname or global name; role names |
| Where the list comes from | the bot’s copy of the group (its Firefly extension with the roster) | the cached channel member list; up to 20 members are looked up one by one with users.info, larger channels through users.list |
with the Server Members intent, Discord’s member list (the first 1000 members by id); without it, the cache, which knows mainly people who have posted |
from_agent set when |
the sender of a group message holds the agent role (the group extension is read once per group message) | the message has a bot_id, is a bot_message, or its sender is in the agent user group (the user group cache lasts 5 minutes) |
the author is a bot or its member roles include the agent role (from the cache) |
| “Replies to the bot” | a reply to a message the bot sent, checked in the local message store | a reply in a thread the bot’s message started: Slack has no reply-to field. The bot remembers its last 4096 posts and otherwise reads the parent once and remembers the answer | a reply whose referenced message is the bot’s; mentions of the bot’s role count as mentions |
| Other content from agents | edits, deletes and reactions are dropped (they never mention the bot) | edits need a mention or a thread reply to the bot; deletes are dropped; reactions pass, flagged | reactions pass, flagged, but reactions from bots are still dropped |
Lupyd also drops the bot’s own direct and group messages, including ones sent from its other
devices. Collaboration added no Slack scopes, Discord intents or permissions: users:read and
usergroups:read were already in the manifest.
admit_direct idempotence
Section titled “admit_direct idempotence”Router::admit_direct calls Platform::admit_direct(user, allowed) the first time a sender
writes in a run (tracked in dm_decided as platform:user), and again after every restart of
Gopala. It has to be idempotent: accepting an already accepted user, or declining an already
declined one, must be harmless. Lupyd checks is_user_accepted before accepting. Slack and
Discord have no message requests for bots, so theirs do nothing; the router drops messages from a
declined sender whatever the platform does.
Security expectations
Section titled “Security expectations”- Credentials come from environment variables named in the provider’s config section. The host
reads them once at startup (
PlatformCredentials::take), removes them from the environment, holds them inZeroizing, and never passes them to a VM or the journal. slack-morphism and twilight keep their ownStringcopies of the tokens for as long as the provider lives. - Persistent state goes under
<data_dir>/<name>/with private permissions (Lupyd’s device and refresh token). Slack and Discord keep nothing on disk. - A conversation id never comes from agent input: the manager only calls a provider with ids
that came from its own events or
joined. - Platform events are untrusted input, and buffers are bounded. Slack’s provider caps its inbox (1024 events), its user cache (50,000) and thread map (4096); Discord’s caps recent messages (20,000) and known users (50,000).