What the agent does
The agent starts with how events reach the listeners, because a retry has to be stopped before any of them run. In an app laid out like slack-samples/bolt-js-starter-template, app.js builds an App from @slack/bolt in Socket Mode with SLACK_BOT_TOKEN and SLACK_APP_TOKEN, LogLevel.DEBUG, and calls registerListeners(app) from listeners/index.js, which registers actions, commands, events, messages, shortcuts and views in turn. listeners/events/app-home-opened.js publishes a Home view on app_home_opened, and manifest.json subscribes the bot to app_home_opened and message.channels. package.json runs tests with node --test tests/**/*.spec.js, lints with Biome, and the six spec files mock client, event and logger the same way. .github/workflows/test.yml runs npm install, npm run lint and npm test on Node 20, 22 and 24.
Slack delivers an event again when it gets no acknowledgement in time, and in Socket Mode the envelope carries retry_attempt and retry_reason, which Bolt exposes as context.retryNum and context.retryReason. The agent adds one global middleware with app.use in app.js, before registerListeners, that reads body.event_id for event payloads and keeps a small in-memory map of ids seen in the last few minutes; an id already seen, or a retryNum above zero, ends the chain without calling next, and the first delivery of any id goes through. The map is kept in its own module under listeners/ so it has a file like everything else and can be swapped for a store later.
Two choices come from reading rather than from the Bolt docs. Slash commands, shortcuts, actions and views have no event_id, so the middleware passes anything without one through untouched rather than inventing a key. And message.channels is the subscription most likely to see retries under load, so the agent writes the test around a message payload as well as app_home_opened, and logs each skip at the app's logger so the debug level already in app.js shows them.
In its sandbox the agent runs npm install, npm run lint and npm test as the workflow does, then adds tests/middleware/dedupe.spec.js in the shape of the existing specs: it calls the middleware with a fake context, body, logger and next from node:test's mock.fn(), asserts next ran once for a fresh id and not for the same id again, not for retryNum: 1, and once for a body with no event_id. The Biome config's rules apply to the new files, so the lint run is part of the proof.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add deduplication of retried Slack events to this Bolt app. Read app.js, listeners/index.js, listeners/events/app-home-opened.js, manifest.json, package.json, biome.json, tests/events/app-home-opened.spec.js and .github/workflows/test.yml first. Write a global middleware, in its own module under listeners/, that for an event payload skips the chain when context.retryNum is above zero or body.event_id was seen within the last few minutes, keeping the ids in an in-memory map that expires them; anything without an event_id passes through. Log each skip through the app logger. Register it with app.use in app.js before registerListeners. Do not change any listener. Run npm install, npm run lint and npm test, add tests/middleware/dedupe.spec.js in the style of the existing specs with mock.fn covering a fresh id, a repeated id, a retryNum above zero and a body with no event_id, and open a pull request quoting the lint and test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds one middleware module and one spec file, and changes app.js by one import and one app.use line. No listener changes, no manifest change and no new dependency. The description quotes the Biome run and the node --test output with the four new cases named beside the existing six spec files' results.
The run's record keeps the full npm install, lint and test logs, so a reviewer can see the test matrix the workflow runs was satisfied on the Node version in the sandbox and read the exact assertions.
Before merging, a reviewer sets how long an id is remembered, and decides whether the in-memory map is enough for how the app is deployed: one process in Socket Mode, which the template is, needs nothing more, while several replicas would each keep their own map and need a shared store.
Run it on every Linear issue labelled slack
A team that maintains several Slack apps makes this a rule. In the Project for each repository, an automation with the prompt above and a linear trigger on linear.issue.labeled for the label slack starts a run when someone files "the welcome message posted three times in #general". The trigger adds the issue after the prompt, so the run reads which event the issue names and writes the spec's payload for it.
Each run opens its own pull request on its own branch and links the issue. An app that already checks retryNum gets a description saying so and a pull request that only adds the event_id map if the issue describes a duplicate that was not marked as a retry.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Duplicate deliveries show up only under load or when a handler is slow, so they are rarely reproduced on a laptop, and the fix is easy to misplace: inside one listener it covers one event, after registerListeners it runs too late. In a Rush sandbox the agent reads where the chain starts, puts the middleware there, and proves each branch with the repository's own node:test mocks rather than against a live workspace.
The lint and test output stay with the run and the pull request quotes them, so the reviewer reads the assertion that a repeated event_id never reached next rather than a description of the idea. Across several apps the job runs in parallel, one sandbox and one pull request each.
Frequently asked questions
Why check both retryNum and event_id?
They catch different cases. retryNum marks a delivery Slack itself knows is a retry. The event_id map also catches a second delivery that arrives while the first is still being handled, which is the case that posts a message twice.
Does this change how fast the app acknowledges?
No. Bolt acknowledges event envelopes before the listeners run, and the middleware does a map lookup. If retries are frequent, the cause is usually a listener that takes too long, and the skip log lines in the pull request point at which event.
What happens with several app processes?
Each process keeps its own map, so a retry routed to a different process is caught only by retryNum. The module is written so the map can be replaced by a shared store; the pull request names that as the next step rather than adding a dependency.
Will slash commands or buttons be affected?
No. Those payloads carry no event_id, and the middleware passes anything without one straight through, which the spec file asserts.
More Bolt for JavaScript jobs
More jobs like this: Turn a Linear label into a PR
- Add dbt Exposures for Your Dashboards from a Linear Issue (dbt)
- Add User Settings to a VS Code Extension (VS Code Extension)
- Add Feature Flags to a .NET API (.NET)