npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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 its thread_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 — codex or 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. The stream reply mode (slack.replies in the config) keeps the placeholder-and-edit rendering instead: post …, edit as deltas arrive (throttled for chat.update limits), show ⚙ tool… status lines, finalize with the full reply. The texts mode is final with 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 lets a span with a ` in it and 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 *.ts keeps 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 under admit: "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 Name for 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 remote permission 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 channels namespace 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 of approvals) 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:

  1. A mention is always for whoever is named. In a thread or out of one, naming an agent hands it the question.
  2. 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.
  3. 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>.homeChannels in the config): there every new top-level message from someone it admits is addressed to it, unless the message names another agent.
  4. 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, then and?, 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.
  5. How an agent listens is the soul's to say. Rules 3 and 4 are the thread mode, the default. A soul with listens: mentions takes only messages that name it, and hears the rest. One with listens: judge hears 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.
  6. 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 most agent, 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-slack

stratus 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:

  1. https://api.slack.com/apps → Create New App → From a manifest → paste manifest/stratus-agent.manifest.json with NAME replaced by the agent's name. The manifest asks for the channels:history / groups:history / mpim:history scopes and the matching message.* events, which is what lets an agent stay in a thread instead of needing a mention every time, and for files: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; leave files:read off 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.
  2. 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 the appToken, xapp-…). It is not on OAuth & Permissions, where the bot token is.
  3. Install App → Install to the workspace → Allow → copy the Bot User OAuth Token (that's the botToken, xoxb-…).
  4. Upload the agent's avatar under Display Information.
  5. Add both tokens under channels.slack.<agentId> in ~/.stratus/credentials.json and restart stratus serve — the log will show slack: <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 &lt;-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. /invite it 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 thread ts, 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 still gated like any other, and approvals.channels still 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:

  1. 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.
  2. Each invite entry 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… or W…).
  3. conversations.create, then setTopic and setPurpose if given, then one conversations.invite with force, 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 with alreadyMember: true. Each refusal is a sentence: a missing channels:join scope with the reinstall step, a private channel, an archived one, one at the member limit. Slack answers channel_not_found both 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… or W… id; the inviting app itself can't be invited), then sends one conversations.invite with force. 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 with invited and notInvited; 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 creator isn'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.