@stratusagent/channel-slack
v0.14.20
Published
Slack adapter for Stratus agents: one Slack app per agent (real avatar and presence), Socket Mode, thread-keyed resumable sessions, and streaming replies via message edits
Readme
@stratusagent/channel-slack
Slack adapter for Stratus agents. One Slack app per agent — Slack has no way to give a single bot several identities with real avatars, presence, and DMs, so each agent gets its own app, and the adapter runs one Socket Mode connection per agent (no public ingress needed; Mac Minis behind NAT are fine).
- Resumable conversations: session keys are
slack:<agent>:<team>:<channel>:<thread_ts ?? ts>(a DM's top level: the DM channel id alone; a thread in a DM adds itsthread_ts) — a thread is a conversation, it survives daemon restarts, and two agents sharing a thread keep fully separate sessions. A turn parked on a human when the daemon died is re-asked after the restart, and a turn that was still running is continued from where it got to (unless the agent runs on a harness —codexor a Claude subscription — where it is failed instead, since the harness may already have acted on it); either way, when it finishes its reply is posted into the thread as a fresh message — the placeholder it would have edited belonged to the old process. - Replies post when they are ready: by default each message is posted once, finished: what the agent writes before its first tool is posted as the tool starts, what it writes between tools after that is not posted, and the reply follows as its own message, with Slack's loading status (
assistant.threads.setStatus— "is thinking…", "is running shell.run…") shown while the turn works, so the notification carries the answer. Thestreamreply mode (slack.repliesin the config) keeps the placeholder-and-edit rendering instead: post…, edit as deltas arrive (throttled forchat.updatelimits), show⚙ tool…status lines, finalize with the full reply. Thetextsmode isfinalwith each paragraph posted as a message of its own (code blocks, lists and a heading with its paragraph kept whole, at most five messages a reply, and a reply that tags another agent kept whole so that agent reads all of it), so an agent reads like someone texting. Either way a reply that outgrows one message is split across several. - Markdown is translated to Slack's mrkdwn on the way out —
**bold**to*bold*,*italic*to_italic_,~~struck~~to~struck~,[text](https://…)to<https://…|text>, and a#heading to a bold line, since mrkdwn has no headings. A bare address is sent as<https://…>, Slack's own link markup, so emphasis around it (**https://…**) cannot be read as part of it, and a*,_, or~inside one is part of the address rather than a marker. Trailing punctuation (.,,,**) and a)the address never opened belong to the sentence, as in GFM autolinks, so…/wiki/Function_(mathematics)stays whole. A bare address is sent as<https://…>, Slack's own link markup, so emphasis around it (**https://…**) cannot be read as part of it, and the*,_, or~inside one is part of the address rather than a marker; trailing punctuation (.,,,**) is the sentence's, as in GFM autolinks. The reply is read once into tokens and written back from those, so what counts as code is decided one time rather than by each rule in turn. Three things follow from that. A code run is one token: nothing reads or rewrites inside it, an unclosed fence included, and the newlines in a fence are not line breaks — so a#on a line of somebody's shell script is not a heading. A run of N backticks opens code and only a run of exactly N closes it, which is what letsa span with a ` in itand a ````-fence holding a ```-fence work; one or two unmatched backticks are text, as they are in Markdown, but a pair is a span however far apart, because Slack pairs them too. A delimiter is matched to its partner, across whatever sits between —**the `fs.read` tool**is bold around a snippet, not four literal asterisks — though never across a line, so a marker still being streamed stays literal until its closing half arrives. A run is spent rather than matched whole, so the three asterisks ending**bold and *italic***close the italic with one and the bold with two; what no pair spends stays on the line as text, and what a run cannot buy — the third tilde of~~~struck~~~, a style that does not exist — is never charged for. A wrapper is only written where its own character is not already loose in what it wraps: Slack has one delimiter per style and no way to nest it, so a heading that already contains bold keeps the bold it has rather than gaining a second pair that would print instead of render, and# glob *.tskeeps an asterisk that was never a marker. A heading sheds its hashes and its trailing spaces from the prose that holds them, never from a snippet. Anything whose spelling already matches — lists, block quotes, inline code — is untouched. A pipe table, which mrkdwn has no syntax for, becomes a code block with its columns padded to line up (alignment colons respected,**/`markers dropped from cells, since nothing renders inside code); a grid wider than 60 characters — past what a phone shows unwrapped — or one with a link in it (a link inside a code block is not clickable) becomes one line per row,*Header*: value · *Header*: value. A one-column table has nothing to line up and becomes a bulleted list under its bold header. A table inside a fence is somebody's text and stays as written, and a grid longer than one message is split like any code block, closed at the cut and reopened in the next, with its header and rule repeated so every part names its columns. - Mention to start, then it stays in the thread. A mention opens a conversation; every later reply in that thread from someone the agent admits reaches it without tagging it again (by default only its listed principals; see Who can talk to an agent), and free-form DMs are unchanged. A mention partway into an existing thread opens the conversation with what was said before it: the thread's parent and its newest 39 earlier messages. A mention at the top of a channel opens with the channel's 20 most recent messages instead, which is where a channel per client or per project keeps its context. Either way each message keeps its own speaker and its own trust, so a principal's mention does not carry a stranger's earlier words in under the principal's label (other bots count as
unknown, and underadmit: "principals"unlisted senders are left out). This needs the history scopes below; without them the agent sees only the message that named it, and the adapter logs a warning. Who an untagged reply is for is decided by Who a message is for. Inbound mentions of other users are humanized to@Display Namefor the model; redeliveries are deduped so a slow turn never runs twice — in memory while the process remembers them, and after a restart by the gateway: each message is dispatched with its own key (idempotencyKey), a repeat runs no second turn, and the adapter posts that message's own reply and files (a file changed since that turn is skipped, since the path may now hold another file), or its failure if the turn failed — once more, if the process died after posting it, which beats a reply never posted. - Approval buttons for the gateway's
remotepermission mode: a gated tool call parks the turn and asks in its thread with Allow once / Always allow / Deny. See Approving tool calls — clicks are authorized by who clicked, never by who can see the message, and Always allow is offered only where the daemon would actually remember it. - Tokens are gateway infrastructure secrets, stored in the
channelsnamespace of~/.stratus/credentials.json— never in an agent's credential allowlist:
{
"channels": {
"slack": {
"blair": { "appToken": "xapp-…", "botToken": "xoxb-…" }
}
}
}- A new agent's app connects without a restart. Saving an agent's tokens (
stratus channel set slack,stratus setup→ Channels, or the dashboard) reloads the running daemon, which connects that app, reconnects one whose tokens changed, and drops one whose tokens were removed or whose soul is gone. Every other app stays connected. The same reload hands each connected app who it answers to now (principals.slackUsers,principals.admit,approvals.slackApprovers,approvals.slackChannel), without reconnecting it: see Changing who an agent answers to. Its other settings (slack, the rest ofapprovals) still come from the config the daemon started with, and a daemon that started with no Slack app at all needs a restart for its first one.
Who a message is for
A mention is how a conversation starts. After that, the thread is the
address — replying in it reaches the agent the way replying to a colleague
reaches them, with no @ and no ceremony. Four rules decide the rest, and
they are the whole model:
- A mention is always for whoever is named. In a thread or out of one, naming an agent hands it the question.
- Inside a thread it is already in, an agent listens without being named. "Already in" means a session exists under that thread's key — which happens only because somebody mentioned it there — so an agent follows conversations it was brought into and nothing else. That record is durable, so a daemon restart mid-thread forgets nothing.
- The room is not a conversation. A channel message outside any thread
is never a follow-up, however much of the channel the app can see. An
agent that has not been spoken to does not join in. The one exception is
an agent's home channel (
slack.agents.<id>.homeChannelsin the config): there every new top-level message from someone it admits is addressed to it, unless the message names another agent. - In a thread with several agents, an untagged reply goes to the agent
the thread belongs to. That is the first agent to hold it: the one its
first message named, or the one that posted it. Naming another agent
gets that agent's answer to that message, and makes the untagged
replies the same person sends after it that agent's too, until they
name someone else (
@Bea your turn, thenand?, is Bea's). The thread itself stays where it was: an untagged reply from anyone who has not named an agent in it goes to its owner. Who each person last named is kept in memory, so after a restart it falls back to the owner. A message an agent already took stays that agent's: Slack redelivering it after a restart goes back to the agent that accepted it — and if that agent's app has not come back, the others stand down rather than run it again. Another app's bot that spoke in the thread before any agent here held it owns it the same way: an agent served by another daemon, or any integration replying in the thread. So does a thread a team agent (agentMentions.team) started. A thread another app started — an alert, a deploy note — is not that app's: it belongs to the first agent named under it. Only who posted and when is kept, not what it said. After a restart the thread is read (conversations.replies) to tell; if that read fails, the sessions decide (the one agent there, or the one that spoke last) and a warning says why. A daemon that did not see a thread begin, and has not read it yet, takes the first agent it saw hold it as the owner. - How an agent listens is the soul's to say. Rules 3 and 4 are the
threadmode, the default. A soul withlistens: mentionstakes only messages that name it, and hears the rest. One withlistens: judgehears everything and runs a turn nobody asked for, told it may answer with nothing, on each untagged message that is its own by rule 4: the agent the sender last named, else the thread's owner (card 541). There is no window: an owner an hour past its last answer still takes an untagged instruction in its thread, and only one agent takes each message. A judged turn reads the message's images and text files as an asked-for turn does, under the same limits; the model gets them after the words that mark the message as not addressed to it, and may still say nothing. An overheard message's files stay names only, and nothing is downloaded for it. Each decision is logged as one line with the agent, the message's ts, and the reason (addressed it last,owner, or whose it was instead), never the text. An approver's untagged stop is never judged: it stops the holder's turn or, with nothing running, is only heard. A turn that decides on silence posts nothing: its placeholder is opened only on the first text it streams, never on a tool line, and a failed one posts no error note — one the daemon died inside, failed at the next start, included, a line it had already streamed staying as it was. A line an attempt the provider abandoned had already posted is taken back when the retry decides on silence. A mentions-only agent takes no part in the holder rule: a thread-rule agent stands down in a thread one owns, since that agent is being talked to and waits to be named. A judging agent that chooses to speak on a turn nobody asked for takes the thread, recorded once its reply has landed (a message typed while it was still deciding stays the previous owner's), and the owner takes it back by answering in it. Which of the two spoke last is read off the thread, not the clock: whichever reply sits lowest, since that is the one a reader answers, and a placeholder posted early and filled in slowly sits above a reply posted while it was being written. A colleague's reply is never judged, only heard. - Standing down is not leaving. An agent in a thread hears what is
said to the other agent in it — the question that named its colleague,
the untagged replies that were the colleague's to answer, and what the
colleague replied — into its own session, with no turn run and
nothing posted. The next time it is asked, it answers as someone who
followed the conversation rather than one who stepped out of the room.
What it hears is marked as said to somebody else, so a stranger's words
in a shared thread never read to it as an instruction. By default an
unlisted sender is not overheard at all; under
"admit": "anyone"a stranger overheard lowers its session's trust label exactly as one who addressed it would, since their text is in the transcript either way. A colleague's reply is heard under the colleague's own label, never as a person's: an agent's word is at mostagent, and carries whatever its session has been exposed to. Replies only — a turn that said nothing, or failed, is nothing to hear — and only while the hearer's app is still in the channel, which is asked of Slack per reply: a person's message reaches an agent through its own socket, so an app removed from a private channel stops hearing on its own, but a reply is forwarded by the daemon and would otherwise keep arriving.
Everyone in the thread is talking to the same agent — a reply from a second
person is a follow-up like any other, and channel messages reach the model
prefixed with the speaker's display name so it knows who said what. A reply
carrying a file, or one the author also broadcast to the channel, is a
follow-up too; what Slack marks as bookkeeping — an edit, a deletion, a
join — is not, and nothing answers it. Images are shown to the model.
A PNG, JPEG, GIF, or WebP attached to a message is downloaded with the
bot token and sent with the message (the token is only ever sent to
https://files.slack.com: a remote file, an app's link to a file it hosts
elsewhere, is named and never fetched) — a screenshot alone, with nothing
typed, is a question in its own right and gets an answer. That needs the
files:read scope, which the shipped manifest asks for; an app installed
without it should have the scope added under OAuth & Permissions and be
reinstalled once, and until then stratus serve warns, naming the scope,
each time an image arrives. An image over 5 MB or 8000 pixels a side (the
model API's limits) is sent as Slack's own largest preview of it, up to 1024
pixels a side, and the message tells the agent it is seeing a scaled preview,
so it asks for a crop rather than guessing at small text; an image Slack made
no preview of is not kept. One message's images stop at 20 MB
together — a request has a size limit too, and images past it are named as
unreadable; send them in a message of their own. The same 20 MB — and 20
images — is what a whole thread's images may take on one request, spent
newest first — and the request as a whole has a limit too, so when the
rest of the conversation needs the room the oldest images give way to it.
Once a thread's images pass a limit the oldest are let
go of — the model is told an image was there and what it was called, and
the session keeps that record rather than the pixels, so a busy thread's
row stays bounded. A message's downloads share one 30-second deadline,
after which whatever has not arrived is named as unreadable, so a slow
link cannot hold the thread. And an image the model API itself refuses —
the adapter checks that a file opens and closes like the image it claims
to be, but that is not a decode — is dropped from the session and the turn
retried without it, so one bad file cannot fail every later turn of a
thread.
An OpenAI-compatible model that takes only text needs "vision": false in
config, which turns every image into that note; see the
Slack guide. Whether the model actually sees the image depends on the
agent's runtime: the Anthropic API, OpenAI-compatible providers, and the
Claude Code runtime send it as image content; the Codex harness takes a
text prompt, so there the agent is told the image's name and that it cannot
see it.
Text files are read into the message. Markdown, plain text, CSV, JSON,
YAML, a log — anything Slack labels text/* (HTML aside), a few text
application/* types, or an unlabelled file whose name says it is one of
those — is downloaded with the same files:read scope and set into the
message after what was said, between [Attached: plan.md. Its contents
follow.] and [End of plan.md]. A text file dropped in alone is a
question, like a screenshot. One file may be 100 KB and one message's text
files 200 KB together, since read text joins the conversation and is sent
again every turn. A larger one, up to 10 MB, is saved under the agent's
workspace (attachments/slack/<stamp>-<file id>-<name>, 0600) when the
host passes attachmentStore, and the message says [Attached: spec.md,
251 KB, too large to include here. It is saved in full at <path>. …]. The
path is recorded in the tainted-write ledger at the sender's label before
the bytes are written, so fs.read of it carries that label. One agent's
saved attachments are bounded together (attachmentStore.maxBytes, 256 MB
by default, and 1,000 files): past it a save is refused, the file reaches the turn as a
name, and the warning names the directory to clear. Nothing is deleted. stratus
serve passes it; a host that does not, or a file over 10 MB, gets the name
only, and stratus serve warns with the file's name. A file that is not UTF-8, or that comes back as
Slack's sign-in page because the scope is missing, is treated as unreadable
and the warning names the scope. Text files share the message's 30-second
download deadline with its images.
Every other attachment is unreadable — a PDF, a Word file, an image that
was too large, a text file over the caps — so the message reaches the agent
naming those files, each with why it was not read (not a kind of file read
here, too large, not downloaded or not in time, not readable, or not opened
because the message was overheard), which is what lets it answer honestly
instead of as though it had read them, or guessing at why. Such a file dropped
in with nothing said is not a question, and gets no reply.
Sessions are still per agent, but a new one opens with what was said
before the mention that created it: in a thread, its parent and newest
earlier messages, and at the top of a channel, the channel's most recent
messages (see the overview above for the limits and the trust rules). That
needs the history scopes; without them an agent hears a thread only from
the mention that brought it in. A colleague's reply is
heard by the daemon that posted it, not through Slack — an agent served by
another daemon is a stranger's bot to this one, and its replies are not
heard at all. They do count for who a thread belongs to (rule 4).
Three edges worth knowing. An agent whose app was installed before the history scopes below is told about mentions only, and behaves exactly as it always did — the workspace's grant is the switch, per app. Where a thread's several agents cannot be ordered — a host whose session routing carries no timestamps — an untagged reply is left alone rather than answered twice; mention the one you want.
A named agent whose app is down answers nothing, and nothing answers in its place: being tagged is a decision about who is being asked, and an agent that has been handed the question elsewhere does not take it back because the other one is offline. That silence is the same signal a mention has always given when an app is down.
And the rules above are mechanical, which shows in a thread where people are mostly talking to each other: an agent invited into one answers every untagged reply in it, including the ones meant for somebody else. Give the side conversation its own thread. It can now hear a thread it is not answering; teaching it to choose — to answer only when it has something to add, and to let "thanks, we've got it" be a sentence it read — is the rest of the reading-the-room work.
What the agent is told about the room
Every turn says which kind of conversation it came from — a direct message
(and with whom, when that is one of the operator's principals: a display
name is text anyone can set, and this lands in the system prompt), a group DM, a private channel, or a public channel — with
its member count, whether the message is in a thread, and whether the
channel is shared with people outside the workspace (is_ext_shared /
is_org_shared from the lookup, or the event's own is_ext_shared_channel,
which is current on every turn). Never the
channel's name, for the same reason: whoever created or renamed the
channel chose it. The agent writes for that audience: a public channel of a thousand
people is not the DM it was in a minute ago, and what it was told in one does
not belong in the other. The kind comes from the event; the count
comes from conversations.info with include_num_members, the same call and
the same channels:read / groups:read / mpim:read scopes
outbound destinations use. It is made on every turn outside a DM and never cached, so a channel
made public, or shared with another workspace, since the last message is
described as it is now; turns in one conversation that overlap share one
call. A DM needs no lookup. An app
without those scopes still tells the agent the kind when the event carries
it, and otherwise only that it is in Slack. The words it is told are in
Agents.
Installing
This package is an optional peer of the CLI — stratus ships without any
transport, so installs that never use Slack do not carry the Slack SDKs
(~9 MB). Add it alongside the CLI to enable the channel:
npm install -g @stratusagent/channel-slackstratus serve picks it up automatically for every roster agent with stored
Slack tokens. Without it, tokens are reported at startup with an install
hint and the daemon serves every other channel as usual.
Setting up an agent's Slack app (~2 minutes)
The easy way: run stratus setup → Channels. It prints the manifest with
the agent's name already filled in, takes both tokens without echoing them,
verifies each against Slack, and stores them under the right agent id — no
editing credentials.json by hand.
The manual equivalent, if you prefer:
- https://api.slack.com/apps → Create New App → From a manifest → paste
manifest/stratus-agent.manifest.jsonwithNAMEreplaced by the agent's name. The manifest asks for thechannels:history/groups:history/mpim:historyscopes and the matchingmessage.*events, which is what lets an agent stay in a thread instead of needing a mention every time, and forfiles:read, which is what lets it see an attached image. An app created before those shipped needs them added under OAuth & Permissions and Event Subscriptions and reinstalled once; leave the history scopes off and it answers mentions and DMs, exactly as it did before, without the earlier messages of a thread it is mentioned into; leavefiles:readoff and it hears about attachments, images and text files alike, by name only. It also turns on the Messages Tab under App Home (features.app_home.messages_tab_enabled), which Slack creates apps without — until it is on, a DM to the app gets Slack's own Sending messages to this app has been turned off and never reaches the adapter. An app created before the manifest carried it needs App Home → Messages Tab → Allow users to send Slash commands and messages from the messages tab switched on once; reopen the DM afterwards. - Still on Basic Information, scroll to App-Level Tokens → Generate Token and Scopes → name it anything → Add Scope →
connections:write→ Generate, and copy the token (that's theappToken,xapp-…). It is not on OAuth & Permissions, where the bot token is. - Install App → Install to the workspace → Allow → copy the Bot User OAuth Token (that's the
botToken,xoxb-…). - Upload the agent's avatar under Display Information.
- Add both tokens under
channels.slack.<agentId>in~/.stratus/credentials.jsonand restartstratus serve— the log will showslack: <agentId> connected.
Approving tool calls
When stratus serve runs with approvals.mode: "remote", a gated tool call
parks the turn and the adapter asks here. The question goes to the thread the
turn is happening in; a turn with no Slack conversation of its own (scheduled
work, a delegate) asks in the configured slackChannel. With no
slackChannel set, a schedule's firing asks in the schedule's own Slack
destination, under its report thread if it has one; a delegate is denied.
The request names the site for a call judged by one (browser.act),
because its arguments are a CSS selector and say nothing about where a click
lands — and that site is what Always allow widens.
Always allow is left off entirely where the daemon would remember
nothing: a dangerous tool, which asks every time whatever is answered; a
browser action whose conversation has no page to grant; and a shell command
the parser cannot reduce to a scope. The prompt says so instead, because a
button that does exactly what Allow once does, under a label promising a
standing grant, is worse than no button.
Where it is offered, a line beside the buttons says what it would do,
because that differs by tool and is the half of the question the button
widens: for most gated tools it is a standing grant to the agent that
lasts until an operator revokes it (stratus grants <agent> lists and
revokes; see Approvals); for a shell
command it is that command's scope; for a browser action it is the site;
for a message read or send it is that tool on that one conversation; and
only for one that names no conversation is it the rest of this session.
The resolved message describes what the daemon did rather than which button
was pressed — POST /approvals accepts always whatever this channel
rendered, so the answer can arrive from somewhere else — and names the grant
that was made, since the request said in advance which kind it would be.
The one thing it cannot promise is the disk write: a daemon that could not
read the whitelist does not write over it, and by then the message is sent.
stratus logs has the exact line.
Who may answer is configured per agent, in ~/.stratus/config.json:
{
"approvals": {
"mode": "remote",
"slackChannel": "C07OPS",
"agents": {
"blair": { "slackApprovers": ["U01DYLAN", "U01OPS"] }
}
}
}That block is only read from a config you chose — --config,
STRATUS_CONFIG, or the global ~/.stratus/config.json. A project-local
stratus.config.json cannot appoint approvers, since it can be checked into
any repository.
Clicks are authorized by actor, not by delivery. Everyone in a thread can
see the request; only the ids listed for that agent can decide it. Anyone
else's click is refused with a notice only they see, and the request stays
open for someone who may actually answer — which matters most for Always
allow, since that widens what the agent may do for the rest of the session.
An agent with no approvers listed denies every request on arrival rather than
leaving it hanging — set "slackApprovers": [] on an agent to exclude it
from a shared default list. The same goes for an agent whose Slack app is
configured here but failed to connect. An agent this adapter was never given
is left alone: a request is a broadcast, and refusing one another channel was
about to answer is not the adapter's call — stratus serve reports agents no
channel can ask for, at startup. Those automatic denials are recorded as
undeliverable rather than decided, so the log never shows a refusal
nobody made as one somebody did.
The message shows the tool's arguments as well as its name — approving
shell.run without seeing what it would run is not approval. Arguments are
escaped, so a model-written argument cannot mention or broadcast to the
workspace through the prompt itself, and long ones are truncated with a
notice saying so.
Requests are also denied, visibly, when they expire, when the turn is cancelled, and when the daemon shuts down. Every ending the daemon is alive for retracts the buttons, so a message does not keep offering a decision that has nowhere to land.
A crash is the ending it cannot be alive for, and the record of what was posted lives only in memory — so a new process cannot find its predecessor's prompts to retract them. Those correct themselves on the next click: it answers that the request is no longer pending and rewrites the message, since the click is the one thing that carries the message's location back. A prompt nobody clicks stays as it was until someone does.
Interactivity must be enabled on the app or Slack delivers no clicks at
all. The shipped manifest turns it on; an app created before this shipped
needs settings.interactivity.is_enabled set to true once, under App
Manifest. No request URL is needed — the clicks arrive over the same Socket
Mode connection.
Credential requests
The same approvers answer an agent's credential.request. The gateway hands
the request to the adapter's requestCredential, the channel contract's
method for this, and waits for it (the adapter sets credentialReplaceForms
and credentialEnvForms, so it is also handed replacements and requests
with env, whose post and form say which variable the agent's shell will
read the key from): the adapter resolves once the form is
posted, and rejects, posting nothing, when the agent has no approvers, the
turn is a DM with someone who is not one of them or a private channel or
group DM none of them is a member of (conversations.info, then
conversations.members, under the read scopes the manifest already has),
the turn is not one the adapter dispatched from a Slack message, or Slack
refuses the post. A public channel is open to everyone in the workspace and
is not checked. When Slack will not answer the membership question, the
form is refused rather than posted on a guess. Where to post comes from that turn (its conversation and
thread), never from session metadata, which a control API caller can write. The gateway then
drops the request and tells the agent why. The request is
posted in the conversation the agent asked in (never an approvalChannel:
the person who can answer is the one the agent is talking to) with an Add
credential button. A click by an approver opens a modal (views.open);
anyone else is told, privately, that they are not an approver. The modal
carries only the request id in private_metadata, so where the key goes and
for whom is the gateway's record of the request, never something a
submission says about itself.
The submission is checked against the approvers again and handed to the
gateway's provideCredential, which stores it add-only and grants it in the
requesting agent's soul. A refusal (a name already stored, an empty value, a
request no longer pending) comes back as a response_action: errors ack,
which keeps the modal open with the reason under the field. A refusal the
gateway marks retired (the name was stored since, or the request is gone)
also rewrites the request message without its button, since no answer could
land on it any more. On success the
request message is rewritten to say what was added, for whom, and by whom,
or, when the key was stored but the soul could not be written, that the
agent cannot use it until the name is added by hand. The submission is
acked within Slack's three-second window: an answer slower than that closes
the modal first, and a refusal arriving after is sent to the submitter as
an ephemeral message in the request's thread.
The value is read from the submission and passed to the gateway; the adapter
never logs it, posts it, or dispatches it. Modals need no scope beyond the bot's,
and arrive over the same Socket Mode connection as clicks. The full flow is
in Slack.
Who counts as the operator
Everything above decides which agent a message is for. None of it decides
who is speaking: the adapter admits a message that has a user, is not a
bot, carries no bookkeeping subtype, and is a DM or a mention — and any
member of the workspace can open a DM or type an @mention. A DM proves
nothing about who is typing.
So a message is the operator's only when the operator has said so:
{
"principals": {
"slackUsers": ["U01DYLAN"],
"agents": {
"blair": { "slackUsers": ["U01DYLAN", "U01OPS"] },
"bea": { "slackUsers": [] }
}
}
}A turn from a listed id reaches the agent as its operator's (user). By
default anyone else gets no turn (see the door below). Under
"admit": "anyone", a turn from anyone else — in a DM as much as in a
channel — reaches it as unknown, and the session it lands in stays unknown from then on: that
text is in the transcript. Every fact the agent remembers afterwards
carries the label, and the prompt renders it under a heading that says so.
With no list at all, nobody is a principal: under the default nobody gets a
turn, under "anyone" every Slack sender is unknown, and stratus serve
says so at startup. An agent's own entry replaces the shared list;
"slackUsers": [] excludes an agent from it.
The list also decides how a speaker is named in a channel turn, which
the model reads as Name: text. A principal is their display name — one
line, at most 80 characters, control characters and Unicode bidi controls
spelled out — because
their profile is trusted the way their messages are. With a list in force,
everyone else is their user id, exactly as an @mention of them already
is: a display name is text its owner typed, and the speaker position of a
user turn is not a place a stranger gets to put a sentence. With no list
at all there is nobody to prefer, so every author keeps their name — and
"no list" is the key being absent; "slackUsers": [] is a list that
prefers nobody, so under it every author is an id.
The sender is judged on every message, not once per thread. A thread
keys one session for everyone in it, so an authorized member can open one
and a stranger can mention the agent inside it afterwards. By default the
stranger's message is refused before it becomes a turn, and the session is
untouched. Under "admit": "anyone" it becomes an unknown turn that
lowers the session, and the authorized member's next turn does not raise it
back.
The list is a door by default: an unlisted sender gets no turn. A
stranger's message is not merely uncertain, it is a prompt they chose, and
an agent that holds tools should not run on it. "admit": "anyone" turns
the list back into a label, where an unlisted sender still gets a turn,
marked unknown. Per agent, as here, where Bea answers anyone:
{
"principals": {
"slackUsers": ["U01DYLAN"],
"admit": "principals",
"agents": {
"bea": { "admit": "anyone" }
}
}
}Under "admit": "principals" (the default; the daemon resolves an absent
key to it, while an embedder calling the adapter directly without admit
still gets anyone) a sender not in slackUsers gets no turn:
the message is refused before it takes a place in the queue, the agent
does not overhear it into a thread's transcript either, and nothing is
posted back — a reply is a conversation the operator chose not to have.
The refusal is one line in the daemon log naming the agent and the user
id — one per message, however many times Slack delivers it, and only for a
message the agent would have taken up: a mention, or a reply in a thread
the agent holds, whether the daemon remembers that or its sessions do. A
stranger's reply in a thread the agent was never part of is dropped
without a line. The daemon's default is "principals"; "anyone" is the
default only for an embedder calling the adapter directly. The key inherits per agent like
slackUsers, so Bea above stays open while everyone else is closed. A value
that is neither word is a config error, never anyone: this is the one
setting here whose misspelling would open the door. So is a slackUsers
that is not a list of user ids, and so is a block or a per-agent entry that
is not an object: dropped for its shape, a per-agent list would fall back to
the shared one, the broader list it existed to narrow, and the block itself
would fall back to anyone.
stratus serve says at startup which agents refuse unlisted senders.
Like approvals, this block is read only from a config you chose —
--config, STRATUS_CONFIG, or the global ~/.stratus/config.json. A
project-local stratus.config.json cannot appoint itself the principal.
The labels themselves are documented in
Memory.
Changing who an agent answers to
The people lists take effect at the next reload, with no restart: who an
agent admits (principals.slackUsers and principals.admit), who may
approve its calls (approvals.slackApprovers), and where it asks
(approvals.slackChannel). Saving settings through the control API
(PUT /config) reloads by itself; after editing the config file by
hand, POST /roster/reload (or stratus restart) applies it. The app
stays connected, and the daemon logs the new counts, such as
slack: ava now admits 3 listed people and has 1 approver.
Someone removed loses access at that reload: their next message is refused, and as an approver they can no longer answer an approval or credential request, including one posted while they were still on the list. Someone added can answer requests posted from then on. The lists are read under the same rules as at start: a project-local config is ignored, and a config that will not read refuses every sender and every approval until it is fixed and reloaded.
Other agents' bots
A bot is never the operator, and by default a bot's message is never a turn.
An agent with slack.agentMentions on (see
the guide) makes
one exception: a team agent that names it, meaning one of this daemon's
agents or one listed in slack.team, narrowed by agentMentionsFrom if
that's set. That message runs a turn in its thread, labelled unknown
whatever principals says, since the other agent's words carry whatever its
own session was exposed to. It can't stop a turn or answer an approval. It
doesn't take the thread for the holder rule, and an untagged bot message
stays nothing. A thread admits at most AGENT_MENTION_HOP_LIMIT (4) agent
mentions in a row per daemon, until a person speaks there again. A refused
team mention is logged once, with the reason.
Reading a channel
The adapter implements the channel contract's readConversation, which is
what the gateway's message.read tool reads through: a channel's top level
(conversations.history, newest first) or one thread
(conversations.replies, root first), paged up to the call's limit. It uses
the channels:history / groups:history and users:read scopes already in
the manifest, so nothing needs reinstalling. Message text comes back as
plain text: mentions, channel links, links, dates, and <-style escapes
are decoded, and a mention is named only for a principal or the agent
itself. message.read also stops at 40,000 characters of text per call and
says more, so a channel of long posts cannot outgrow the model's context.
The boundary is the outbound one plus a rule for DMs:
- The agent's own app reads. An agent with no Slack app here reads nothing, and another agent's app is never borrowed.
- The app must be a member of the channel, public or private.
/inviteit where it should read. - DMs and group DMs are refused, member or not, except the one the session reading is in. What someone says in a DM is said to the people in it; a read from elsewhere, a public thread above all, would carry it to people who were never in the room. This is not an approval: the gateway refuses a DM read before anyone is asked, and tells the agent approval can't unlock it.
- The session's own DM is readable, top level and threads, so an agent
in a DM can look back past what its session holds (a thread session, or
one started over). The check is the session id, read without a lookup
(
sessionConversation): it must be exactly this app's key for that DM,slack:<agent>:<team>:<conversation>or that plus one threadts, and the gateway and the adapter both ask it. A delegated or scheduled session, an archived one, another agent's app and another workspace never match. The read is stillgatedlike any other, andapprovals.channelsstill never covers a DM. Anyone holding the gateway token can open a session under any id; that is the operator, who can read what the bot token reads anyway.
Messages come back as plain text with author ids and, where Slack supplies
one cheaply, a display name. Every attached file is listed by name. The
tool labels the result external, so what an agent remembers after reading
carries that label.
Images on the messages read are shown to the model too, when the read asks
for them (ConversationReadRequest.images). message.read asks whenever
the agent's runtime can show an image, for at most 5 images and 10 MB per
read. They go through the same reader as a message's attachments at the
start of a turn: Slack's metadata is checked first, then the bytes, and only
the four types a model takes (PNG, JPEG, GIF, WebP) are fetched, only from
https://files.slack.com. An image over 5 MB or 8,000 pixels a side is sent
as Slack's largest preview of it, and the agent is told it is a preview.
The cap is spent in the order the messages come back (newest first at the
top level, root first in a thread) and the files within each. Once one image
doesn't fit, none after it is fetched, and one 30-second deadline covers
every download in the read. Each message names the images it showed in
shownImages, and says in imageNotes why any other image file was not
shown: a preview, too large, a download that failed or ran out of time, a
type no model takes, or the read's cap. Reading fewer messages shows the
rest. Other files are never downloaded by a read. This needs the
files:read scope that turn-start images already use.
A read of a channel's top level with no before or after, the first
page, also lists the channel's bookmarks (bookmarks.list, asked beside
the history and only after the checks above pass), so an agent told "the
doc is in the bookmarks" can find it. Each comes back as a title and a
link, nothing else: a title over 200 characters is cut, and a link over
2,000 is replaced by a note, since a cut link is a broken one. A thread or
a later page lists none, so paging costs no extra calls. This needs the
bookmarks:read scope, which the manifest asks for. An app created before
it reads messages exactly as before, and its first-page reads carry
bookmarksUnavailable, a sentence telling the agent the scope is missing;
any other failure to list them is said the same way, and the messages come
back either way. In message.read, bookmarks come first and may use 16,000
of its 40,000 characters, which holds Slack's limit of 100 at a typical
length. Any that don't fit are counted in bookmarksOmitted.
Creating a channel
The adapter implements the channel contract's createConversation, which
is what the gateway's channel.create tool runs on. The agent's own
app creates the channel, so it is the first member, and its token never
leaves the adapter. The order:
- Everything Slack would refuse once the channel exists is refused first,
with a sentence and nothing created: a name that isn't lowercase
letters, numbers, hyphens and underscores, or is over 80 characters (a
leading
#is dropped); a topic or purpose over 250 characters; more than 1,000 people to invite. - Each
inviteentry is resolved. An agent id on this host becomes the Slack user its app posts as, in the same workspace only; the creating agent is a member already. Anything else must be a Slack user id (U…orW…). conversations.create, thensetTopicandsetPurposeif given, then oneconversations.invitewithforce, so a bad id doesn't stop the good ones.
A create Slack refuses is a sentence: a missing scope names
channels:manage (public) or groups:write (private) and the reinstall
step, and a taken name says so in words (Slack's names are unique, archived
channels included, so a retried create can't make a second channel).
Anything that fails after the channel exists doesn't undo it: the result
lists notInvited and notSet, each with the reason. When an invitation
call fails without naming everyone, the channel's members decide who was
added, and anyone that can't be checked is reported as unknown rather than
claimed.
Both scopes are left out of the default manifest, because they let an app create and manage channels and most agents never need that. Add them to the apps that should, under OAuth & Permissions, and reinstall.
Joining a channel and inviting people
The adapter also implements joinConversation and inviteToConversation,
which the gateway's channel.join and channel.invite tools run on. Both
use the agent's own app and take the channel's id (C…, from the
channel's link or a message), never its name. Their results name the
channel by id only, because a channel's name and topic are whatever its
members typed.
- Join calls
conversations.join, which works on public channels only. Slack never lets an app join a private channel on its own: a member has to invite it (/invite @app). Joining a channel the app is already in succeeds withalreadyMember: true. Each refusal is a sentence: a missingchannels:joinscope with the reinstall step, a private channel, an archived one, one at the member limit. Slack answerschannel_not_foundboth for a wrong id and for a private channel the app can't see, so that sentence names both. When Slack's answer leaves it unknown whether the app joined (internal_error,fatal_error, or no answer), the call says so; trying again is safe. - Invite resolves each entry the way a create does (agent ids become
their app's Slack user in the same workspace; anything else must be a
U…orW…id; the inviting app itself can't be invited), then sends oneconversations.invitewithforce. It rejects only when nobody was invited: an empty list or more than 1,000 people, or a whole call Slack refused (not_in_channel,missing_scope,is_archived,channel_not_found,method_not_supported_for_channel_type,no_user,ratelimited, or a refused token). Every other outcome resolves withinvitedandnotInvited; a failure that may have partly worked is settled by the channel's members, as for a new channel.
Scopes, all left out of the default manifest: channels:join to join;
channels:write.invites (public) or groups:write.invites (private) to
invite, where channels:manage and groups:write also work. Add them to
the apps that should have them, under OAuth & Permissions, and
reinstall.
Archiving a channel
The adapter implements archiveConversation, which the gateway's
channel.archive tool runs on, with the agent's own app and the
channel's id (C…). It archives only a channel that app created. It first
asks conversations.info and refuses, before Slack is asked to archive:
- a channel whose
creatorisn't the app's bot user, or that has none; - a direct message or group DM;
- a channel shared with another workspace or organization (
is_shared,is_ext_shared,is_org_shared,is_pending_ext_shared), since a person outside this workspace would be affected; - any channel at all when another agent on this host uses the same app (the same bot token, or the same bot user in the same workspace).
That last rule is why ownership needs one app per agent, as the rest of
this adapter does: creator names the app's bot user, so two agents on one
app can't tell their channels apart. The check sees only this process, and
two daemons on one app's tokens are not a supported setup.
A channel already archived resolves with alreadyArchived: true, so a retry
changes nothing. Slack's refusals become sentences: a missing
channels:manage (public) or groups:write (private) scope with the
reinstall step, an app that is no longer a member (not_in_channel), a
workspace rule limiting who can archive (restricted_action), rate limits
and refused tokens. When Slack's answer leaves the outcome unknown
(internal_error, fatal_error, or no answer), the call says the channel
may be archived and that trying again is safe. Results and refusals name the
channel by id only.
Archiving can't be undone by the agent: Slack doesn't let bot tokens call
conversations.unarchive. Messages are kept, and a person can unarchive the
channel in Slack. The gateway also refuses the conversation the agent was
asked from, so a reply always has somewhere to go.
No new scope: an app with the channel.create scopes can archive.
Speaking first: the outbound seam
The adapter also implements the channel contract's resolveOutbound — how a
scheduled turn's message.send reaches a channel, and how a schedule's
destination is validated at creation. The address is the agent plus a
conversation id (C…/G…/D…, never a name): each agent is its own Slack
app, possibly in its own workspace, so the id alone names nothing.
Validation is membership: the app must be able to see the conversation
(conversations.info) and be a member of it — /invite it where it should
report. A DM id passes on its own, because a D… conversation exists only
because someone opened it with the app; the adapter never opens new DMs, so
an agent cannot cold-message a workspace. A person's user id (U…, or W…
on Enterprise Grid) is refused with that reason: name the D… id of a DM
they already have with the app instead. This is what the
channels:read / groups:read / mpim:read scopes in the manifest are
for — an app created before this shipped needs them added under OAuth &
Permissions and reinstalled once, or every destination reads as invisible.
A reply names its thread by the ts of the thread's first message. Slack posts
a reply to a ts it has no message for at the top level and still answers
ok, so the adapter checks where Slack put the first chunk: when it landed at
the top level, the adapter deletes it, sends nothing more, and refuses with
"C… has no thread …". If the delete fails, the refusal says the message
is still at the top level and gives its ts.
