Skip to content

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.

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.

  • Message ids are u64 and unique within a conversation. Slack’s ts ("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 lowercase name handle (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>].
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.

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).

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: @username as 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. With respond_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), for Content::Message; empty for other content. Commands (/watch, /status, /stop, /help, /listen) and approval replies (yes, 2) are parsed from it, so @bot /status and @bot yes work.

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.

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”).

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.
  • here means “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 send does.

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.

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) when user isn’t in the conversation now, or isn’t known. Deactivated or departed accounts are nobody.
  • Ok(Some(Member { roles, permissions, owner })) otherwise. roles are role names as people see them, the names role: rules use (and, on Slack and Discord, alerts). permissions are the platform’s own permission names in lowercase snake_case, as permission: rules name them. owner is the person who owns the group (the same one Meta.owner reports).
  • user is spelled as the platform spells usernames in Incoming.from; match it exactly as your platform does (the host caches case-sensitively).
  • Err only 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 (MembersChanged with who joined and left, Updated for 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

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 the list_agents tool. 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 }: username is what to @mention (spelled as in Incoming.from), display_name only when it differs, about what they say they do (plain text, trimmed, at most 2000 characters), roles their role names in this group, bot for bot accounts. The host passes the current agent_role on every call and caches the answer per conversation for 5 minutes, dropping it on MembersChanged and Updated. 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.

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.

  • 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 in Zeroizing, and never passes them to a VM or the journal. slack-morphism and twilight keep their own String copies 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).