Slack agent delivery¶
Two ways to answer in Slack¶
| Webhook connector | Slack app | |
|---|---|---|
| Where | Go, in humagen serve (pkg/integrations/slack) |
TypeScript, apps/slack, a separate process |
| How Slack reaches it | Signed webhooks to a public URL | Socket Mode, no public URL |
| How it reaches Humagen | In process | The HTTP API, as a machine. Under tailscale sign-in the server that starts it makes its credential (security) |
| A run looks like | One plain message per run, edited with chat.update |
Humagen components: native streaming, plans, tool steps, failures with Retry, files. See steps, command output and run details |
| Agent session status and the stop button | Yes | Yes |
| Code channel slash commands | Yes | Yes: each command in the client's slack.commands, registered with agents.conversations.setCommands when a message is accepted in the channel. Ordinary channels use /skill |
/agent, shortcuts, Home tab |
No | Yes, from Humagen's sandbox manifest |
| Inbox items about a run | No | In the run's thread, and on Home |
| Several apps per workspace, as clients | Yes: tenant, limits and allow-list come from the client | Reads one client's default agent and allow-list, in full as the client's slack.machine, though they name an agent that lives in a project the machine may not read. A mapped person's messages are the client's (threads with a surface, below); anyone else's runs are not yet recorded as the client's |
| Channels bound to projects | Yes: a run in a bound Slack channel is filed in the channel it is bound to, and an untagged one answered by that channel's chain, else in the client's home | Yes: a mapped person's Slack thread is a Humagen thread filed by the binding, someone the client maps to nobody is refused in a bound channel, and announcements reach a bound general channel, caught up on after a restart or a reconnect, where a reply that mentions the app starts a thread seeded with the announcement |
| Mentions of a person | No | In their direct messages with the app, with Open Thread and Reply, unless they are in the Slack thread already (they wrote there or were mentioned there with <@U…>). Experts named by a role are each told |
Background work and notify |
No | A reply in the app's Slack thread the work was asked from, naming the person, with its one line and Open Session; else in their direct messages. See background results |
| Who asked | Recorded on the run, and the run acts for the person the team's clients map the Slack user to | Recorded as the person, and acts for them, when the app's client maps them (act_as): their message is theirs in the Humagen thread, and so are the runs it starts. Else as the app, acting for nobody. Tools that act as a person use the person's own credential |
| Questions a run waits on | No | In the run's thread, answered for the person the client maps. See below |
| Tokens and cost | No | Never on a turn. A finished turn offers Run Details to a person the client maps, answered to them alone. See steps, command output and run details |
Use the connector for several apps per workspace, and where a public URL is fine. Use the Slack app for the console's experience in Slack, or where nothing may listen on a public address. Do not point both at the same Slack app: both would answer.
The app acts for a person only as a client whose slack.machine is its
credential and whose slack.people maps them. An app the server starts
(surfaces.slack) gets that client from the Platform document: people, and
under a sign-in other than tailscale also machine, make the server keep
the record slack-app-<team> and start the app with HUMAGEN_CLIENT naming
it. With no people there is no record and no HUMAGEN_CLIENT, and the app
acts for nobody. That record has no bot token, so files attached in Slack are
not read through it. See
the spec.
The rest of this page describes the connector. The app is described in its README.
What the API lacks for the Slack app¶
The app works around each of these and says where in its README.
| Missing | Effect today | Proposal |
|---|---|---|
actor on POST /api/runs for anyone |
Runs are recorded as the Slack person only when the app's client maps them (act_as, see clients); anyone else's run is the app's |
Built for mapped people. A Slack person nobody mapped stays unnamed on purpose |
client on POST /api/runs, or a machine bound to a client |
The client's run limits and allow-list are not applied by the platform, except that * for a person the client acts for (act_as) asks only the client's agents whether to join. The app sends * only for a client whose list is * |
Bind a machine credential to one client (a client claim, or a client_id on the token mapped in the client record) so the platform places its runs as it places webhook runs |
metadata on POST /api/runs |
The Slack team, channel and thread a run answers are not on the run; the app derives them from the run id instead | Accept a bounded metadata map (string keys and values, a few hundred bytes) and return it on the run, so a surface can find its own place without encoding it in the idempotency key |
| A router preview that knows a client's allow-list | A client with a list and no default answers nothing, and a default of * is not sent for a client with a list: the platform would ask agents past it |
GET /api/join?client= and the same rule in POST /api/runs |
| The run a retry started, in the resolve response | Retry from Slack starts its own run and acknowledges the inbox part | Return {message, run} from POST /api/inbox/{id}/parts/{part}/resolve |
| Feedback with comments | Built: like and dislike open a comment modal and save the rating even when skipped | PUT /api/runs/{id}/feedback stores a run reference, rating, reason and comment; the run provides context; GET collects paginated records |
| A modal to type a reply to a question | Built for a question in the inbox, a mention in a person's direct messages, and Something Else on a run's own card in its thread | None |
| A consequence and a recommended mark on a question's options | Not shown: Question.options is a list of labels |
Options as objects with a label, an optional one-line consequence and an optional recommended flag |
| The approval agent's fields and references on the run's question | The card in the run's thread says what the agent decided and why: an allow or deny from the run's answer, and any judgement from the inbox while the app follows the run. A card the app no longer follows (after a restart, or a run that went quiet) shows only the reason from the answer | Carry judgement on the run's question as the inbox part does |
Steps, command output and run details¶
What a turn's work looks like in Slack depends on how the turn was written.
| While the turn is going | Once it has ended | |
|---|---|---|
| Streamed natively | Slack's own task cards, one per tool call, from chat.appendStream |
The same cards stay. The final blocks add what is below |
| Posted and edited (streaming refused, a bridged outcome, a run that ended while the app was away) | One line per run of tool calls, in order. The last says what is running now | One line that counts the work by kind: Ran 3 commands (1 failed), read 2 files, updated 4 files (+120 -18), ran 2 searches |
The count uses the kinds every tool line uses (lineKind in
packages/components/src/timeline.ts, and fileEdits for files written), in
the order each kind first came. A turn that made one call still says what it
was pointed at (Read docker.go). A call to another agent keeps its own row
either way, and a turn with a plan keeps its plan.
Command output. The platform's shell tool answers with exit <code> and
then the end of the command's output, for a command that failed as for one that
passed, so a non-zero exit arrives as a completed call
(run.delta.tool.done.v1). The app reads the command from the call's arguments
and the exit code from that first line (commandResult in
packages/core/src/command.ts):
- A command that passed stays a count. Its output is not shown.
- A command that failed, and that no later call ran again with success, is
shown under the answer with its command,
exit <code>, how long it took and the last 40 lines of its output. This holds for a streamed turn too. - The newest three are shown. Earlier ones are counted in a line above them.
- The exit code is shown only for a failure. A command tool that reports no exit line is shown as failed only when the call itself failed, with no code.
- The working directory is not shown: the stream does not carry it.
A bridged outcome carries no steps, so it shows none of this.
Run details. A turn never shows tokens or cost, since a whole channel reads
it. A finished, failed or stopped turn offers Run Details instead, when the
app's client names the app as its slack.machine and maps at least one person.
A click answers the person who clicked, alone, in an ephemeral message in the
thread:
| Shown | From GET /api/runs/{id} |
|---|---|
| Agent | agent |
| Model | usage.context.model, the model of the run's latest call |
| Input tokens, and how many came from cache | usage.total.prompt_tokens, usage.total.cached_prompt_tokens |
| Output tokens | usage.total.completion_tokens |
| Cost | usage.total.cost, in its own currency. "At least" when unpriced_calls is not zero or some calls were priced in another currency. "Not priced" when there are tokens and no cost, never zero |
| Elapsed | updated_at less created_at, for a run that has ended. It includes time the run waited on a person |
total counts the run's own model calls and the attached runs it waited on. A
figure the run did not record has no row.
The run is read as the person who clicked (act_as_client and act_as_user),
never as the app's machine, so Humagen decides: a person sees a run's usage in
Slack only where they may read the run. A person who may not is told they have
no access, with no figures. A Slack user the client maps to nobody is told to
ask an admin to connect their account, and Humagen is not asked. A bridged
outcome does not offer the button.
Questions a run waits on¶
The Slack app shows a run's question in the run's thread: the streamed message
is closed with Humagen's approval or choice card, so its buttons can be pressed.
A click answers through Humagen (answerQuestion) as the person the app's
client maps the Slack user to; a Slack user it does not map is told in Humagen's
words that they cannot, and Humagen is not asked. Humagen decides the rest:
who may answer is the run's spec's to say, and a refusal is shown with Humagen's
noPermission copy. The card settles in place from the run's own events,
whoever answered, and the answer continues in a new message. A question's inbox
message is not posted in the thread again. Configure the client with the app's
credential and the people it answers for:
"slack": {"machine": "<subject of the app's machine credential>", "people": {"U01ANA": "ana@example.com"}}
Under tailscale sign-in the app's subject is slack-app:<team id>, such as
slack-app:T0123ABCD, and a mapped person is tailscale:<login>.
Ask a Question on an approval opens a form for one question. Sent, the
question is said in the thread (who asked, about which action, and what)
and asked of the agent that made the call, as a message typed in the
console while a run waits is: by a mapped person as their own message in the
conversation (POST /api/threads with act_as), by anyone else through the
app, as a mention there would be. It is answered beside the call, not behind
it: the call's card keeps waiting with its buttons, and the answer streams
below it. Deciding stays with Approve and Decline. In a bound channel only a
mapped person may ask.
The approval agent. A conversation has two approval modes, as in the
console: Ask, where a person approves every gated action, and Auto,
where the approval agent decides gated actions, answers what the conversation
already settles, and asks a person when unsure. In Slack, an approval waiting
in a run's thread has a menu after its buttons with one row, Set this
thread to Auto, where the app's client maps people. It sets
the conversation the thread is (PUT /api/threads/{id}/approval with
act_as), with the same checks as the console's toggle, made as the person
who pressed: Humagen decides whether they may, and its refusal is said to
them alone. A Slack user the client maps to nobody is told they cannot, and
Humagen is not asked. The change is said in the thread, naming who made it:
the approval agent approves and answers from the next action on, as that
person could, and an action already waiting still waits for a person. Under
it, Switch to Ask sets the conversation back, and that change is said the
same way, with Switch to Auto under it.
A call the approval agent decided settles its card with what it decided and
why, as the inbox shows it (Approval agent: Allowed: "<reason>" beside who
set the conversation to Auto). What it said about a call it handed to a
person is put on the card while it waits, from the inbox, when the app is
following the run.
The webhook connector shows a parked run as a suspended session and does not take answers.
Coworking: channels, threads and mentions¶
A project's owners bind a Humagen channel to a Slack channel the app's bot is
already in (PUT /api/projects/{name}/channels/{channel} with
slack: {client, channel}, or slack: on the channel in the Platform
document). Binding one, or moving a binding, also takes clients:write: a
binding files every new thread in that Slack channel in the project, so which
channels a project answers in is the client's admins' to decide. An owner
keeps or removes a binding an admin made. One Slack channel is bound to one channel, a direct message never,
and archiving a channel unbinds it. GET /api/clients/{id}/bindings lists a
client's. A client's home (a project and one of its channels) is where
everything else is filed.
When the app listens¶
The Slack app listens on a mention, and after one. Nothing else is heard.
| In Slack | What the app does |
|---|---|
| A direct message | Answers. Every message there is addressed to it |
| A message that mentions the app, anywhere in it | Answers that message |
| A mention in a channel thread's first message | Answers, and once the answer is in, the thread is listened to (listening on the thread). A refused mention, a failed run, or one still quiet or waiting on someone starts no listening |
| A later reply in a listened thread that mentions nobody, from the person whose mention the app answered most recently there | Reads it and asks the agent whether it calls for it (POST /api/threads with listen). The agent answers, or the message is kept as what was said and nothing shows in Slack |
| A mention in a reply of a thread that did not begin with one | Answers once, with what was said in the thread since it was last asked. The thread is not listened to |
| A reply that mentions nobody in a thread that is not listened to, or from anyone else in a listened one | Not heard, and not kept (409). A late answer to an older mention does not hand the thread back |
| A reply that mentions nobody, which Humagen could not take (an error, or no answer from it) | Nothing shows in Slack: no notice, no reaction, no status. It is logged. A mention or a direct message that fails is told why |
A reply that tags only other people, a user group, or the whole channel (@here, @channel, @everyone) |
Not offered: it is addressed to them. One that also mentions the app or names an agent is asked |
| A channel message that mentions nobody, outside a thread | Not heard. In a Slack channel bound to a project it is recorded there, as every message in a bound channel is |
| A message from the app itself, another bot, an edit or a join | Never starts anything |
The whole message is sent, as the person wrote it. The app's own mention tags nobody: one that opens the message is the address and is dropped, with the colon or comma after it, and anywhere else it reads as the app's name, so "could @Humagen take a look" asks "could Humagen take a look".
Only a person the client maps is listened to. The agent's answer to "does this call for me?" is the one a message that names no agent is routed by (overview): a no, a failure and no agent to ask all leave the message unanswered.
A thread is filed where its Slack channel is bound, else in the client's
home. A client with no home files in the workspace's root, in no project,
so no project lists its sessions: give it one (PUT /api/clients/{id}, or the
client's page in the console). A person's own project is not a place a client
can file in: a machine never reads one, so the app could not show the answer.
For a person the client maps, the Slack app posts each message into the Humagen
thread its Slack thread is, as that person (POST /api/threads with
surface {client, channel, ts, message, app_user} and act_as). Only the
client's slack.machine may, and the platform decides where the thread goes:
| Slack | Humagen |
|---|---|
| A thread in a bound channel | A shared thread in the bound channel |
| A thread in an unbound channel | A shared thread in the client's home |
| A direct message, or the assistant pane | A private thread in the client's home |
The platform reads Slack's text in the one tag grammar: the app's own mention
is not a tag, a bot in client.bots is its agent, a person in slack.people
is their handle, and anyone else stays plain and is refused. When the app is
mentioned in a thread, the people's messages since it was last asked there are
posted first, each as its person and posted only, so the room in Humagen reads as
it did in Slack. Each message is posted once by its ts: a redelivered event
answers repeated and starts nothing again. A channel thread whose first
message mentioned the app is listened to once the app has answered there
(When the app listens): a reply that mentions nobody,
from the person whose mention the app answered most recently there, is offered
to the agent, and replies from anyone else start nothing, so people talking to
each other in the thread are never answered. Only the newest answered mention
moves whom the thread listens to; the listener's unmentioned replies never do.
A bound channel whose client's own subscriptions name channel messages has
them mirrored as before, and none is offered. A thread stays with the agent it was asked for: the one agent a
message tags, once it answers, becomes the thread's selected agent, and the
thread's selected agents answer its untagged messages ahead of any default,
until a message tags another (RFC 0012). Outside a bound channel the
client's default answers an untagged message in a thread nobody tagged; the client's allow-list holds
everywhere, and for a default of * only the agents on a client's list are
asked to join. @auto tags nobody. The machine reads every thread on its
own surface, wherever it is filed, but a person it posts or answers for is held to where they may
read: someone who may not read a project's runs answers no question there,
even on a card in a channel bound to it. A bound channel is a project's
channel, so only people the client maps post there: anyone else who mentions
the app in one is told to ask an admin to connect their Slack account, and
Humagen is not asked. Elsewhere they ask through the app as before. When Humagen
cannot say which channels are bound, the app answers nobody it would ask as
itself: the turn is refused as Humagen being unavailable, and the next one reads
the bindings again.
An announcement of a project whose general channel is bound is posted there,
top-level, once; the app records where (PUT /api/inbox/{id}/deliveries/{client}),
and that receipt is the record of the post, so an edit, a withdrawal or a
restart updates that post instead of posting again. Once the announcement
is withdrawn the post says only "This announcement was withdrawn.", and the
app records the same post again, so the receipt says the post shows the
withdrawal. A draft never reaches a channel, and a post offers nothing that
would set it aside for one reader: it is the channel's. The app's machine
is told of a bound project's announcements wherever it may see the project,
though it is only a viewer there. A members-only project's reach Slack only
where its owners name the machine among its members: binding its general
channel alone sends nothing.
The event stream does not replay what it carried while the app was not
listening, so each time the stream opens, when the app starts and after
every reconnect, the app catches up. For each project whose general channel
is bound to its client it reads the project's newest 50 announcements,
withdrawn ones too, as its machine reads them (GET /api/projects/{name}/inbox,
where the machine is shown its own client's receipts and nobody else any),
and compares them with its receipts:
- a post whose announcement changed since its receipt says the post showed
it (
updated_atafter the receipt'sat), as when it was withdrawn, is edited, and its receipt recorded again; - an open announcement it has no receipt for is posted, oldest first, when it
was announced in the last 24 hours and no earlier than the Slack channel
was bound there (
bound_atonGET /api/clients/{id}/bindings, kept while the binding holds and moved when it is made again or moved).
So the release notes Humagen posts at start (workspace.release_notes), before
the app connects, reach a channel bound to the workspace's general, once it
was bound before that start. The bounds keep a reconnect to one read a
bound project, and keep from the channel what is no longer news: a post a
day late reads as new, and what was announced before the channel was bound,
or while it was unbound, is not posted at all. What falls outside them
stays in Humagen's inbox and on the Home tab. A change is caught up on only in
the newest 50: an older announcement edited or withdrawn while the app was
not listening keeps its post as it was, withdrawn words included, until a
later notice about it. Only bound projects are caught up on: once a Slack
channel is unbound, or bound to another project, its old posts are left as
they are.
The app catches up, and posts announcements at all, only when its client
names the app's own credential as its machine (slack.machine): Humagen shows
the client's receipts to that credential alone, so any other would post
everything again. It logs that it skipped the catch-up and why. A catch-up
that could not read Humagen, or could not bring a post up to date because Humagen
was away, is tried again after 5 seconds, then twice as long each time up to
5 minutes, until one finishes. What would answer the same next time is
logged and skipped, not tried again until the next catch-up: a bound project
the machine may not read (403 or 404), such as a members-only one that does
not name it, a receipt Humagen refuses the machine the same way, and a post
Slack refuses to edit, such as one deleted there. None holds up another. A
notice that comes during a catch-up never posts twice: the app looks at each
announcement one look at a time, reads it afresh each time, receipt and
all, and posts only what has none. A notice posts an announcement with no
receipt only as a catch-up would: open, from the last day, and announced
after the binding. Humagen dates a receipt when it takes it, so after each
receipt the app reads the announcement once more and shows a change made
meanwhile, which no catch-up would see. A post whose receipt Humagen did not
take, as when it went away just then, is recorded at the next look rather
than posted again, while the app keeps running.
A reply in an announcement's Slack thread starts a shared thread seeded with
the announcement. The manifest subscribes to message.channels and
message.groups so the app can listen in a thread that began with a mention
(When the app listens), and the app drops every other channel message that does not mention it unread,
unless the client's own subscriptions name channel messages. So the reply
that mentions the app is the one that reaches Humagen, and the replies before it that did not are posted
ahead of it as the room, each as its person and posted only. The app posts
them as for any Slack thread, with the post's surface: the platform finds
the announcement by the receipt the app recorded at that channel and ts, and
starts the thread in the bound channel with it. Its turns start with the
announcement, from the person who posted it, for a recap the agent the
schedule ran, or for release notes Humagen itself, never from whoever replied;
then comes the reply, the person's
own message, read in the one grammar and answered by the channel's chain as
any message there. What the announcement says tags nobody. A later reply
finds the same thread by its surface. The thread reads the announcement as
it stands, so once it is withdrawn the thread says only that. Someone the
client maps to nobody is told to connect their Slack account, as anywhere in
a bound channel. A thread is seeded only where the Slack channel's binding
files it in the announcement's own project, so only those who see that
project read it. There a reply under an announcement that was withdrawn
before anyone replied starts nothing, and the app says so (Humagen answers
410); a draft never reaches a channel. After the Slack channel is bound to
another project, or unbound, a reply under an old post starts a thread where
it is now filed, as any other, open or withdrawn: nothing of the
announcement comes with it, and nobody there is told what became of it. So
does a reply under an announcement withdrawn longer ago than the
workspace's inbox retention (workspace.inbox_retention, 90 days by
default), which Humagen has dropped, receipt and all.
Once a thread is seeded, the announcement is part of it and of what its runs
are sent, so it is read as they are, with runs:read, and not as the inbox
reads it, with projects:read.
A mention of a mapped person, or a question addressed to them, reaches the
app's event stream with for {client, user}. The app reads it for them
(act_as_client and act_as_user on GET /api/inbox/{id}) and posts it to
their direct messages with Open Thread and Reply, unless it was raised in a
Slack thread of the app's own, where Slack told them already. Reply opens a
modal; sending it posts in the thread as the person (act_as on
POST /api/threads/{id}/messages), which settles their mention, or answers
the question.
Background results¶
A result that background work sent when it ended
on its own (a watch that fired or ran out, a goal or a task), or that notify
sent, reaches the event stream of a client's machine with for {client,
user} when the client maps the person it is for. No other result does. When
the work was asked in a Slack thread of a Slack client, only that client hears
of it, and the notice also carries reply_in {channel, ts, session}: the app
reads the message for the person, as above, and replies once in that thread
with <@user>, the message's subject made unable to ping or link, and Open
Session, which opens session (the watch's checks or the task's run) or else
the conversation. The details are never posted there, and the reply is never
edited. The server leaves reply_in out, and the app sends the whole message
to the person's direct messages instead, when the work was asked anywhere
else, when the person may no longer read that conversation, or when a run
behind it (the one that asked, or the last check or turn) read private
context, as a schedule's answer is kept for its creator. A
background result is sent to their direct messages even about a Slack thread
they are in: nothing there pinged them. Work a person stopped tells nobody.
The Home tab of a mapped person is the shared Home, everything on it read for
them the same way: their open inbox and announcements (GET /api/inbox) and
their projects (GET /api/projects, both with act_as_client and
act_as_user), so it holds only what that person may read. It shows at most
five messages that need them, newest first, with the rest counted as Humagen
counts what may need them (open): an agent's draft waiting on them as an
owner is one of them, and a posted announcement is not. They are read with
needs=true, which leaves posted announcements out before the page is cut, so
however much news is newer the rows and their count agree. What's new holds
five announcements of their projects, read with news=true so an agent's
draft never crowds them off the page, unread first, posted ones only. Your
projects holds the projects that name them, which Humagen marks mine: they are
a member or an owner there through an entry for their subject or a
role:<name> they hold, on the project itself or as an owner of a project
above it. A project they see only through *, or only through
projects:govern, is not theirs. At most eight, where something happened most
recently first and then in the tree's order, archived ones left out, and the
rest counted in "N more in Projects", which links the console's Projects. Each
opens its page in the console when the app has the console's address
(HUMAGEN_PUBLIC_URL). An address on the app's own machine, such as
localhost or 127.0.0.1, counts as none: nobody else in Slack can open it,
so the app says so at start and posts no console links. Without one, what needs them has Review, which sends the
message to their direct messages with the app, where it can be answered, and
What's new and Your projects are shown to read. A press on what Review sent is
the person's own, done for them through the client even where the app may read
the message too, and Retry asks the run again in its own thread. Neither it
nor a mention's message offers Snooze or Dismiss: Humagen does those only as the
caller, so in Slack they would be the app's. Ask a Question and Build an Agent
open a form, and the words are posted as the person in their direct messages
with the app, as the shortcut's are; Build an Agent tags @humagen, and
is offered only where the client may reach it. Search Context opens the
console. The tab shows no access or connections, which the app cannot know for
the person. Their projects are left out when they cannot be read: the app's
machine needs humagen:projects:read for them, and the person projects:read.
Someone the client maps to nobody sees the mailbox, as before: an operator the
whole inbox the app may read, anyone else what they may settle.
The webhook connector files its runs by the same binding: a run in a bound Slack channel is in the channel it is bound to, anything else in the client's home, whatever the payload said. A mention that names no agent is answered as it would be in a thread there: in a bound channel by the bound channel's default and then its project's, never the client's; in the home by the client's default first.
The Slack connector accepts signed mentions, direct messages and code channel slash commands. Responses use one message per run, edited as events arrive.
App definition¶
examples/slack/manifest.json declares
the app: an agent view, a bot user, code channels, and the scopes and events the
connector uses. Replace YOUR_HOST with the public address of humagen serve,
then create the app from the manifest at https://api.slack.com/apps.
| Manifest entry | Why the connector needs it |
|---|---|
app_mentions:read, app_mention |
A mention in a channel raises a run. |
im:history, message.im |
A direct message raises a run. |
channels:history, groups:history, mpim:history, message.channels, message.groups, message.mpim |
The replies in a thread that began with a mention, which the app listens to. |
chat:write |
Post and edit the run's message; report session status. |
reactions:write |
The slack_add_reaction action. |
agent_view, assistant:write |
Declares the app an agent, which sessions require. |
agent_session_stopped |
Shows Slack's stop button on a working session and delivers the press. |
code_channels, code_channels:manage |
Register and receive slash commands. |
Slack sends events to /connectors/slack and command invocations to
/connectors/slack/commands. Both are verified with the same signing secret
before anything is parsed.
Configuration¶
Each Slack app is a client: its team and app id, its secrets, the agents it may reach, and the options on this page. A workspace may have several, and every app posts to the same two URLs. The request goes to the client whose signing secret verifies it.
For a single app, these variables create the default client, default-slack:
| Variable | Meaning |
|---|---|
HUMAGEN_SLACK_TOKEN |
Bot token (xoxb-). Required with the signing secret. |
HUMAGEN_SLACK_SIGNING_SECRET |
Authenticates every inbound request. |
HUMAGEN_SLACK_TEAM |
Team id the client serves. A request for another team is a 404. |
HUMAGEN_SLACK_APP |
App id. Optional for one app, required of each when a team has several. |
HUMAGEN_SLACK_BOTS |
U08BOT=docs-bot pairs: which agent a bot user id stands for. |
HUMAGEN_SLACK_DEFAULT_AGENT |
Answers a mention or command that named no agent. |
HUMAGEN_SLACK_SESSIONS |
true reports run lifecycle as session status. |
HUMAGEN_SLACK_COMMANDS |
JSON array of commands to offer in code channels. |
export HUMAGEN_SLACK_SESSIONS=true
export HUMAGEN_SLACK_COMMANDS='[{"name":"create-pr","description":"Open a pull request","argument_hint":"[title]"}]'
Malformed values fail startup. So do commands Slack would refuse: more than 10, a name over 31 characters, a leading slash, a missing description, a duplicate. The same values on a client created through the API are refused with a 400.
| Variable | Client field |
|---|---|
HUMAGEN_SLACK_TOKEN, HUMAGEN_SLACK_SIGNING_SECRET |
credentials.token, credentials.signing_secret |
HUMAGEN_SLACK_TEAM, HUMAGEN_SLACK_APP |
identity.team, identity.app_id |
HUMAGEN_SLACK_BOTS |
bots |
HUMAGEN_SLACK_DEFAULT_AGENT |
default_agent |
HUMAGEN_SLACK_SESSIONS, HUMAGEN_SLACK_COMMANDS |
slack.sessions, slack.commands |
The default client may route to any agent. One created through the API routes
to its default agent and its agents list, and to nothing else.
Session status¶
With sessions on, each lifecycle event calls agents.sessions.setStatus:
| Run event | Session status | What Slack shows |
|---|---|---|
| accepted, started, resumed | processing |
The "Working…" indicator. |
| parked | suspended |
Waiting on the user. |
| completed, failed, stopped | active |
Ready for the next prompt. |
A failed or stopped run reports active because its error, or its partial
answer marked stopped, is rendered in the run's own message and the thread
remains usable. The connector never reports closed.
A session is a thread in an ordinary channel and the whole channel in a code
channel. The trigger cannot tell the two apart, so the sink sends the thread
first and repeats without it when Slack answers thread_ts_not_allowed.
The Slack app's status line¶
The Slack app
also shows one line above the reply box while a run works, as other Slack
agents do: "Checking recent deploys", "Testing Plaud alerts". It is the title
of the step running now, else the plan's title, else "Thinking"
(lifecycle in packages/render-slack/src/lifecycle.ts), on one line of at
most 50 characters, cut with an ellipsis. Slack documents no length of its
own for it.
agents.sessions.setStatus takes only the session state, so the line is set
with assistant.threads.setStatus (channel_id, thread_ts, status),
which needs the assistant:write scope the app's manifest already has
(statusLine in the sandbox's capabilities):
| When | Call |
|---|---|
| The run starts, or resumes after a question | The line, at once, after the session is set to processing. |
| The step changes | The new line, only when it differs, and no sooner than 2.5 seconds after the last one. The latest line waiting is sent when the time is up, whether or not anything else happens. |
| The run waits on a person, completes, fails or stops | status: "", at once and before the session status, so no held line follows it. |
A code channel's session has no thread, so it gets no line. A thread that refuses one (for example where Slack keeps the status to assistant threads) is logged and not asked again during that turn; the answer never depends on it. The connector sets no line.
Stopping a run¶
Slack shows a stop button on a processing session because the manifest
subscribes to agent_session_stopped. A press is handled in the order Slack
asks for:
- Every run answering in that session is asked to stop through the runtime,
with the reason
Stopped by slack:<user id>. Runs attached to it are asked too; runs it delegated carry on. A stop on a code channel covers every run in the channel. Stopped by @user.is posted in the session.- The session is set to
active.
The model call in flight is cancelled. The run ends with run.stopped.v1,
and fiber's sink edits the run's message to keep what the agent had said,
marked stopped with the reason underneath. From the press until that event,
nothing the run still publishes sets the session back to working, and the
active it reports on ending is where the session stays. A run whose turn
finished before the request reached it ends completed, as usual.
A second press, or Slack redelivering the first, finds no run left to stop and posts nothing. Anyone who can see the button may press it: the session, not a console role, is the authority. If the runtime cannot carry the request, the press is answered with an error so Slack redelivers it, and nothing is posted.
A follow-up mention in the thread is answered by a new run. Slack mentions do
not carry the thread's history in Humagen today, so that run is not sent the
stopped turn. A conversation in the console is: see
Stopping a run. Carrying a Slack thread's
history needs fiber's thread journal (runtime.WithThreads), which records a
stopped turn with its partial answer and a fixed marker.
A press reaches only the runs its own client raised. Two apps answering in one thread each hold their own sessions, and another workspace's app in the same team cannot stop a run it did not raise.
Which runs a session holds is remembered in memory, per client. After a restart, or after the client is changed, the button still settles the status but finds no run to stop.
Check the manifest with the Slack CLI from examples/slack:
Slash commands¶
Commands are registered with agents.conversations.setCommands the first time a
run is accepted in a channel. Slack answers not_agent_channel for an ordinary
channel; that outcome is remembered, so it costs one call per channel per
process.
An invocation becomes a tag whose text is what a human would have typed:
/create-pr Fix the flaky login test. The agent is the one named in the text
with @name, otherwise the default agent. The answer is a top-level message in
the code channel. With no agent configured, the invoker gets an ephemeral
message saying so.
Errors¶
Slack reports failures as ok: false with a code. For status and command
calls Humagen logs permanent refusal codes as warnings and still treats the event as
delivered: the answer is already on the surface, and retrying a refusal would
never succeed. Transport failures and transient Slack server/rate-limit errors
are returned, so the router retries them with its bounded backoff.
| Code | Usual cause |
|---|---|
feature_disabled |
Agent sessions are not enabled for the workspace. |
missing_scope |
The installed app predates a scope in the manifest. Reinstall. |
thread_ts_required |
A top-level route in an ordinary channel has no session. |
no_actions_url |
The manifest has no slash_command_url. |
colliding_with_builtin |
A command shares a name with a Slack command. |
too_many_commands |
Other agents in the channel already use the 10 slots. |
not_authorized |
The app is not the channel's agent bot. |
Remaining work¶
- Creating code channels. The connector answers in code channels that
already exist. It does not call
agents.conversations.create, set context bar items, publish views or archive. - Unmentioned messages in a code channel. Only mentions and commands raise
runs there;
message.sessionis not handled. - Session titles and renames are left to Slack and its users.
- Native streaming. The connector edits answers with
chat.update. The Slack app streams them. - Command registration, lifecycle replay cursors and the runs a session holds are bounded, in memory and per client, like the sink's message handles. A restart forgets them, and so does changing the client.
Code channels and agent sessions are new Slack surfaces. This connector is tested against the documented contract through the in-memory fake and has not yet been exercised against a live workspace.
Durable native session feedback¶
Managed webhook installations show lifecycle with reactions on the original thread message: eyes while working, a check on success, x on failure, raising hand when waiting and raised hand when stopped. The app needs reactions write permission. A reaction failure is retried independently of delivering the answer. The answer retains native user/channel mentions and HTTPS permalinks.
A plain reply in a thread with a persisted agent answer continues its agent's session. A standalone thanks in that known thread receives a heart reaction without starting a model turn. Bot messages and unknown unmentioned channel threads do not start work.
Signed thumbs-up/down reactions on delivered agent answers save the same
run.feedback.v1 assessment as console feedback, including reaction removal.
A raised-hand reaction stops the known run through the installation's existing
stop policy. Subscribe to reaction_added and reaction_removed, and include
them in an installation's explicit event capabilities when those are configured.
Delivery handles and native event IDs persist across connector rebuilds.
Cross-surface slack_post_message actions require an explicit destination channel
in slack.action_channels. This is an exact channel-ID list; project bindings,
installation capabilities and runtime action policy still constrain the write.