Multiplayer agent harness for work.
Slack surface (Socket Mode)
The Slack surface, run in-process with the agent core: core boots it when Slack tokens are present in its env and hands it a direct client into core's services. Socket Mode means no public URL, ingress, domain, or TLS — it opens an outbound WebSocket to Slack, so you can run it from a laptop or any box with internet.
Slack ⇄ (WebSocket) slack surface (in core) ── direct calls ──▶ core services (Pi)
1. Create the Slack app (one paste)
- Go to https://api.slack.com/apps → Create New App → From a manifest.
- Pick your workspace, paste
manifest.json, create. - Install to Workspace (OAuth & Permissions → Install). Copy the
Bot User OAuth Token →
xoxb-…→SLACK_BOT_TOKEN. - Basic Information → App-Level Tokens → Generate Token and Scopes: add the
connections:writescope, generate. Copyxapp-…→SLACK_APP_TOKEN.
(Socket Mode is already enabled by the manifest. No request URLs to configure.)
Slack Agents (top-bar pin)
The manifest enables Slack's Agents & AI Apps
feature (agent_view) so users can pin the app to the Slack top bar and open it anywhere.
Conversations in the resulting split pane are ordinary DM thread messages and flow through
the normal DM machinery unchanged. Thread titles, context passing and suggested prompts
are not implemented. Activity cards are experimental and off by default.
Two caveats:
- Paid plan required. Slack only serves the AI-apps experience on paid plans (the Developer Program sandbox also works).
- Existing installs must update the manifest and reinstall to pick up the
assistant:writescope and theassistant_thread_startedandassistant_thread_context_changedevents (Slack requires both to enable the feature; the plugin acknowledges them as no-ops). Installs that don't update keep working exactly as before.
Optional activity cards
In Admin → Customize → Feature flags, enable Slack loading indicator (experimental)
for selected people or conversation scopes. It is off by default. The Slack app must
support task_card
blocks and have chat:write.
After QM commits to answering, one card is posted in the existing reply thread and updated in place: Working, Waiting to resume, Background work, Monitoring, or No active work. This describes recorded activity, not success, failure or delivery. Quiet ambient turns and unthreaded DMs do not create cards. Cards are visible to everyone in their thread; own status cards and edits are excluded from conversation history.
Waiting cards survive turns and restarts. Only this conversation's registered background jobs and enabled, unexpired process monitors count, not recurring crons or agent prose. Unwatched exits become visible when checked, reconciled during sandbox setup, or expired. Commands and monitor instructions are never rendered. After more than five minutes, including waits, a subtle Follow via QM Web link opens the exact web conversation with normal authorization. Without a configured web URL, the link is omitted.
A minute sweep refreshes activity and retries transient failures. Durable receipts and
per-thread leases preserve card identity across workers; expired run leases are shown as
waiting, not working. Slack has no conditional writes: late updates are repaired, and an
ambiguous initial post can duplicate if Slack does not deduplicate client_msg_id.
An outage can leave a stale card until recovery. Status calls have a separate five-second
timeout and never delay reply delivery.
Once no activity remains, the card settles without a spinner and is no longer tracked. Later work creates a fresh card. Disabling the flag settles existing cards without stopping work or deleting messages. Native session status and Stop events are not used.
Running locally alongside another developer? Each dev needs their OWN app. See Local dev with multiple developers below — set the manifest
name/display_nametoagent-<yourname>before creating, so you don't share a bot identity.
2. Run
One process — core boots the Slack surface itself when the tokens are in its env:
cd ~/Programming/qm
nvm use
HARNESS=pi ORG_ID=acme ANTHROPIC_API_KEY=… \
SLACK_BOT_TOKEN=xoxb-… SLACK_APP_TOKEN=xapp-… \
npm start
(OPENAI_API_KEY or OPENROUTER_API_KEY works in place of ANTHROPIC_API_KEY; the base
model follows whichever provider you configure.)
(Or put the tokens in the repo-root .env — npm start loads it via
node --env-file-if-exists.) It logs connected as @agent … when live; without
the tokens, core simply runs without Slack.
3. Use it
- DM the bot anything → it replies in the DM (one continuous session per DM). While it's working on your reply you'll see a ⚙ Working… status message; once the agent starts producing text, the reply streams in place by editing that same message — so the wait is never blank and there's never a duplicate post.
- @mention it in a channel → it replies in a thread (one session per thread). After a real Slack mention in that thread, just keep talking in the thread — no need to re-@mention. The bot then listens to every reply and decides whether to chime in like a thoughtful coworker (a "turn detection" step in the core): it answers a question or a request aimed at it, but stays out of a back-and-forth between other people. When it decides to stay quiet it posts nothing at all (no spinner, no "I'll stay out of it"). An explicit @mention always gets a reply, and a new top-level message still needs an @mention to start a fresh thread.
- Share a file with it (DM or @mention with an attachment) → it downloads the file
and the agent can read/process it; ask it to send a file and it uploads the produced
file back into the thread. Bytes travel out-of-band: the plugin streams them to the
core's blob endpoint (
POST /v1/blobs) and the turn carries only a lightweightblobId, so files up to ~1 GB (Slack's own per-file limit), up to 10 per message, ride the same path — no more squeezing base64 into the 1 MB turn body. Outbound files are fetched back from the core (GET /v1/blobs/:id) and uploaded viafiles.uploadV2. Only Slack-hosted files are ingested — externally-hosted ("remote") files are refused, since fetching an off-Slack URL from the plugin host would be an SSRF / token-leak vector. - Replies render natively. The agent emits standard Markdown; the plugin translates it
to Slack "mrkdwn" before posting (
toSlackMrkdwninlib.ts) so**bold**,[links](url),# headers, and- bulletsshow as Slack styling instead of raw markup. - The agent can react with emoji — a Slack-only feature with two paths.
For explicit reaction requests inside a normal assistant turn, the plugin teaches the agent the
reply convention via a surface instruction in the turn's
gatewayContext(REACTION_INSTRUCTION): include a directive like[[react: eyes white_check_mark]]anywhere in the reply. The reply can be just the directive with no other text — the agent then reacts silently, the way a human drops a 👍 without typing anything (no "(no response)" placeholder, and the streamed status is torn down cleanly rather than flashing an empty bubble). The plugin parses the directive out of the reply (extractReactionsinlib.ts), removes it from the text, and applies the emoji withreactions.addto the message that triggered the turn — or, when the directive carries an@ <id>target ([[react: tada @ ~abc123]]), to that specific earlier message instead. So the agent can resolve a phrase like "react to Alice's last message," each channel turn reconstructs the conversation as structured roled turns (renderConversationView, fed by a best-effortconversations.history/repliesfetch that reuses thechannels:history/groups:historyscopes); every reaction-eligible message carries a short, stable id in brackets like[~abc123]— the message's Slacktspacked into base36 (encodeTs), written once on that message's turn. The agent copies that~idinto the directive and the plugin decodes it straight back to thets(decodeTs— no lookup map), validated against the set of message ts it actually showed this turn so a stale/forged id is dropped rather than reacting to the wrong message. The id is short (~10 chars vs a 17-char raw timestamp) and STABLE (it always points at the same message, so persisting it never drifts, unlike the old positional[N]handle). A raw@ <ts>still works for back-compat. In-thread replies are tagged(reply)so the agent sees thread structure, and the parent of any listed reply is pulled in alongside it (recentWindow/arrangeForDisplay). The bot token never leaves the plugin. Names are normalized against the complete Slack emoji set —:eyes:,eyes, or a literal char all work, including the ~1900 standard emoji, ZWJ sequences (🧑💻→technologist), the❤️/❤variation-selector forms, and skin tones (👍🏽→+1::skin-tone-4). That table (src/emoji-map.ts) is built at module load from theemoji-datasourcepackage (iamcal/emoji-data, the dataset Slack itself uses) — bump the dependency to refresh it. Names are deduped and capped; a per-emoji failure (or a missing scope) is logged, never breaking the reply. The directive is also stripped from streamed partials so it never flashes while the reply types out. Separately, unprompted channel-thread messages can be acknowledged before the assistant turn runs: Slack passesgatewayContext.reactionGuidance, the core detector may returnstatus: "react"with emoji names, and the plugin applies those to the triggering message without posting a reply. - The agent also HEARS reactions — if someone reacts to a message, it can see it. With the
reactions:readscope and thereaction_added/reaction_removedevents, a reaction the bot has a stake in is surfaced to the agent: a reaction on its own message, a reaction in a DM with it, or one on a thread root it's following (shouldSurfaceReactioninlib.ts). Everything else — a stray reaction in a channel it merely sits in — is ignored, so a busy channel never floods the agent. A relevant reaction is delivered as an unprompted turn (exactly like a thread-follow message): the core runs turn detection, so a passing 👍 stays silent while a ✅ on the bot's "shall I deploy?" gets acted on. The reacted message is read once viareactions.getso the agent sees its text and its full current emoji set — e.g. "Alice reacted with :white_check_mark: on your message: …(it now has :white_check_mark: :eyes:)" (buildReactionTurnText). The bot's own reactions never loop back, and the same emoji the agent can read on recent messages are appended to the reaction-targeting list (buildRecentMessages), so it can read the slackmojis there too. The reactor is classified and the channel audience is computed exactly as for a message — so a reaction in a Slack-Connect / guest-containing context never makes the bot respond — and that full audience is resolved (stake → dedup → coalesce → membership) before any message content is read, so a non-internal channel's content is never fetched. A burst of reactions on one message is collapsed to a single turn while one is in flight (reactionsInFlightguard), so an emoji-pile can't wake the agent once per emoji. (Bounded by design: a reaction on someone else's non-root reply inside a followed thread isn't surfaced — the message thread-follow path owns that conversation.) - Dangerous commands ask for approval in Slack. When a tool call hits a
require_approvalcommand-policy rule, the bot posts buttons for Allow once, Allow session, Allow always, and Deny. Session/always approvals are exact-command grants; deny rules still cannot be bypassed. This works whether the turn paused awaiting approval (pending_approval) or finished with a reply but skipped the gated command (collect-modeok+pendingApprovals, what the real Pi harness does) — in the latter case the buttons are posted alongside the reply. Clicking re-runs the turn with the command approved. - Hand-offs are plain DMs. When channel work needs another member's own logins, files or
memory, the agent follows the
hand-offskill: in Open conversations it uses the requester's own access; otherwise it sends that person a DM throughPOST /v1/reachwith the full request, and says so only after reach confirms who it matched. - In an externally-shared (Slack Connect) channel, or any channel/mpim whose audience includes a guest or external member, it stays silent in-channel and replies privately (ephemeral) — and uploads no file there — internal-only (spec §9). Group DMs (mpim) aren't handled yet (it says so out-of-band rather than mis-scoping them).
Re-install after upgrading to file sharing. The
files:read/files:writescopes were added tomanifest.json; update the app's scopes (or re-create from the manifest) and reinstall to the workspace so Slack grants them, then restart the plugin.
Re-install after upgrading to emoji reactions. The
reactions:writescope was added tomanifest.json. Update the app from the manifest and reinstall to the workspace so Slack grants it, then restart the plugin — otherwise the agent's reactions are silently dropped (logged as a missing-scope hint).
Re-install after upgrading to inbound reactions. The
reactions:readscope and thereaction_added/reaction_removedevents were added tomanifest.json. Update the app from the manifest and reinstall to the workspace (re-subscribing the events), then restart the plugin — otherwise the bot won't receive reactions others add, andreactions.getreads fail.
Re-install after upgrading to workspace emoji. The
emoji:readscope lets the acknowledgment picker include custom workspace emoji. Update the app from the manifest and reinstall to the workspace, then restart the plugin.
Re-install after upgrading to thread-follow. The
channels:history/groups:historyscopes and themessage.channels/message.groupsevents were added tomanifest.json. Update the app from the manifest and reinstall to the workspace (and re-subscribe the events), then restart the plugin — otherwise the bot won't see non-mention thread replies.
Re-install after upgrading to approval buttons. The manifest now enables Slack interactivity so Block Kit button clicks are delivered as Socket Mode
block_actionspayloads. No public request URL is needed, but the app must be updated from the manifest and reinstalled.
Re-install after upgrading to group-DM thread-follow. The
message.mpimevent and thempim:write/mpim:historyscopes were added tomanifest.json. Update the app from the manifest and reinstall to the workspace (re-subscribing the events), then restart the plugin — otherwise the bot won't see non-mention messages in group DMs (mpims), so it only ever responds there when explicitly @-mentioned.
Local dev with multiple developers
Slack Socket Mode load-balances events across every client connected to the same app. If two developers both run this plugin against one shared app, Slack delivers each incoming message to only one of them (round-robin) — so you each lose ~half your messages, and a message can land on a teammate whose core is down. More config won't fix it; the collision is the shared app identity.
Fix: one Slack app per developer. Separate apps = separate bot identities, and Slack delivers each app's events only to that app's own connection — zero contention.
Each developer, once:
- Create your own app from
manifest.json(step 1 above), but first change the manifest'snametoAgent (yourname)andbot_user.display_nametoagent-yourname. Install it; grab your ownxoxb-…+xapp-…. - Put your tokens in the repo-root
.env(gitignored — see.env.example). Pick a distinct corePORTper dev if you share a machine. npm startat the repo root. In Slack, talk to your bot:@agent-yourname/ DM it.
Nothing shared, nothing to coordinate. The repo's manifest.json is the template;
your per-dev name + tokens live only in your local app and your gitignored .env.
How it maps to the core
| Slack | Core |
|---|---|
app_mention / message.im |
POST /v1/turns |
message.channels / message.groups in a thread where the bot has a stake (it posted or was really @mentioned) |
POST /v1/turns with unprompted: true (+ serialized conversation context) → core runs turn detection; status: "silent" ⇒ post nothing; status: "react" ⇒ add reactions and post nothing |
reaction_added / reaction_removed on a message the bot has a stake in (DM / own message / followed root) |
reactions.get to read the message + its emoji → POST /v1/turns with unprompted: true → core runs turn detection; status: "silent" ⇒ post nothing; status: "react" ⇒ add reactions and post nothing |
user id + users.info (guest/restricted/other-team → guest) |
actor + isExternalGuest |
conversations.info.is_ext_shared |
audience contains a non-internal member → core refuses |
| DM channel | threadRef = dm:<channel> (one continuous session per DM — channel-scoped; the assistant thread_ts only routes the reply + native typing status, never session identity) |
channel thread_ts (root) |
threadRef = ch:<channel>:<root> (one session per thread) |
TurnResult.reply |
posted in-thread; unprompted refused (security_quarantine included) → silent, addressed refused → requester-only (ephemeral in channels) except addressed security_quarantine → fixed in-thread acknowledgement; pending_approval (or ok + pendingApprovals, collect-mode) → Block Kit approval buttons |
Block Kit approval button (block_actions) |
POST /v1/turns with approval (once / session / always / deny) |
Pending /v1/surface-context request (hanging long-poll, source-authed) |
The agent's mid-turn context pull: core resolved the target (current conversation via the capability's opaque destination, or a directory-resolved public channel) and parked the request; the plugin enforces visibility (public, bot-member, not externally shared — or the current conversation itself, even private), fetches history with before paging + match filtering, and POSTs the messages back (buildContextWindow). The default injected window is small (MAX_RECENT_MESSAGES, env SLACK_RECENT_MESSAGES); context beyond it is pull, not push |
Notes / next
- The failed-turn admin link needs no Slack config: when a turn comes back
refusedwith a real failure, the core supplies the admin transcript deep link (TurnResult.adminUrl, built from the session org's portal) and the plugin appends it asFull error:. Absent when there's nothing to link (boundary refusals, no portal configured). - Channel audience is enumerated per-member:
computeChannelAudience(lib.ts) resolves the full member list (with a Slack-Connect / guest external marker, and an actor-only fallback when membership is unreadable) so the core's audience-floor is fine-grained.
History page size
SLACK_HISTORY_LIMIT optionally sets the live history/replies page size and default
read_thread result count for workspace-owned apps (integer 1–200). Without it,
owned apps request 200-message pages and return up to 100 messages by default.
Shared-app installations use 15 for both defaults regardless of this setting.
An explicit tool count overrides the result count, but not the live page size.
Stored mirror reads keep their existing window; shadow comparisons match the live page size.
Mirror qualification
SLACK_CONTEXT_SOURCE controls conversation context and default Slack tool reads:
live(default) keeps Slack history as the source, including automatic channel thread expansion.shadowreturns the same live context while comparing stored events in the background. It logsslack_mirror_shadowcounts for missing messages, text differences, and missing thread parents. It does not log message text or channel identifiers, backfill history, or wait for comparison before returning context. The live page is snapshotted before callers add trigger context, and shadow uses the same stored-message selection as mirror mode. Thread selection matches Slack’s first page, including its limitation that newer replies beyond that page may be absent. Channel roots use the newest page, and thread expansion truncation is tracked separately from root-page truncation. An extra stored row distinguishes exactly full pages from truncated pages; it does not prove complete Slack coverage. Counts cover raw message fields, not complete rendered context or author/subtype fidelity. At most one comparison runs per Slack client; concurrent reads are not all sampled.mirrorexplicitly enables stored context and mirror search, with the documented partial coverage and bounded live fallback. Keep this opt-in until shadow evidence and development qualification are satisfactory.
Ingestion continues in every mode. Shadow mismatch counts describe the sampled live window, not complete channel coverage. Compare channel and thread samples, edits/deletes, and normal agent turns before enabling mirror reads. No automatic mode promotion occurs.
Slack mirror records preserve provider subtypes so stored context uses the same system-message filtering as live context. A missing stored subtype means legacy or unobserved metadata; an empty subtype means a verified ordinary message. Partial event updates preserve omitted subtype and thread metadata. Mirror-mode history fallback shares event content normalization and prefers fresh Slack duplicates; live and shadow reads never backfill their comparison source.