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 |
| A run looks like | One plain message per run, edited with chat.update |
Humagen components: native streaming, plans, tool steps, failures with Retry, files |
| Agent session status and the stop button | Yes | Yes |
| Code channel slash commands | Yes | No |
/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 |
| 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 | No. See usage on a turn |
Use the connector for code channels, 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 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 and a mention in a person's direct messages. Something Else on a run's own card still points to the console | Open the reply modal from the run's card too |
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"}}
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.
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. Outside a bound channel the
client's default answers an untagged message; 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. Slack delivers a message in a channel thread to the app
only when it mentions the app: the manifest subscribes to app_mention, and
to message.im for direct messages alone, and adding message.channels
would widen what the app reads. 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.
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). 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. |
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.
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.