Skip to content

feat(agentex): deliver Slack webhook triggers over Socket Mode - #486

Merged
kenairhodesScale merged 18 commits into
mainfrom
kenairhodes/slack-socket-mode-bridge
Nov 19, 2026
Merged

kenairhodesScale merged 18 commits into
mainfrom
kenairhodes/slack-socket-mode-bridge

Conversation

@kenairhodesScale

@kenairhodesScale kenairhodesScale commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Lets a Slack webhook trigger receive events over Socket Mode, for agentex installs that Slack can't reach over HTTP.

  • POST /agent_api_keys/webhook-trigger takes an optional app_token (xapp-…). Registration checks with Slack that the token belongs to the app in name, then stores it encrypted in a new slack_socket_mode_apps table, one row per app.
  • A separate process, python -m src.run_slack_socket_mode_bridge, holds one socket per app and POSTs each event to the agent's forward_path, signed as Slack would sign it. An event is acked only after the agent accepts it; otherwise Slack redelivers it.
  • PUT /agent_api_keys/{id}/slack_socket_mode switches an existing Slack trigger to Socket Mode or replaces its token and path; DELETE on the same path turns it off.
  • Needs AGENTEX_CREDENTIAL_ENCRYPTION_KEY. New dependency: slack-sdk.
  • Local dev: AGENTEX_CREDENTIAL_ENCRYPTION_KEY=... docker compose --profile slack-socket-mode up also runs the bridge.

Registration and connecting

sequenceDiagram
    participant C as Caller
    participant API as agentex API
    participant DB as Postgres
    participant B as Bridge process
    participant S as Slack
    participant A as Agent

    C->>API: POST /agent_api_keys/webhook-trigger (name, secret, forward_path, app_token)
    API->>S: apps.connections.open + read hello
    S-->>API: connection_info.app_id
    alt app_id != name, or token rejected
        API-->>C: 400
    else app already served by another trigger
        API-->>C: 409
    else
        API->>DB: insert trigger + slack_socket_mode_apps row (one transaction)
        API-->>C: 200
    end

    loop every 60s
        B->>DB: list Socket Mode apps on live agents
        B->>S: apps.connections.open, open WebSocket
        S-->>B: hello (app_id must match, else close)
    end
Loading

A message from Slack

sequenceDiagram
    participant U as Slack user
    participant S as Slack
    participant B as Bridge replica
    participant DB as Postgres
    participant A as Agent

    U->>S: posts a message the app subscribes to
    S->>B: events_api envelope (envelope_id, payload, retry_attempt) on one of the app's sockets
    B->>DB: load the trigger's agent
    alt agent deleted or has no acp_url
        Note over B: no ack
    else
        B->>B: sign payload with the trigger's signing secret
        B->>A: POST {acp_url}/{forward_path}, same body as an HTTP delivery, X-Slack-Signature, X-Slack-Request-Timestamp (+ X-Slack-Retry-Num/Reason on a redelivery)
        alt 2xx within 2.5s
            B->>S: ack envelope_id
        else non-2xx with X-Slack-No-Retry: 1
            B->>S: ack envelope_id (agent declined a redelivery)
        else other status, timeout or error
            Note over B: no ack
        end
    end
    opt not acked
        S->>B: redeliver with retry_attempt + 1, possibly to another replica
    end
Loading

Testing

  • Unit tests for the route, use case and bridge.
  • Postgres integration tests for the new table: one owner per app, cascade on trigger delete.
  • End-to-end tests with the real route, Postgres and slack_sdk client against a fake Slack and a fake agent.
  • Real Alembic migration, downgrade and re-upgrade run locally under docker compose, with the bridge container up and its probes answering.
  • Run end to end against a real Slack app in a sandbox workspace, through the local docker compose stack: registration's app-id check passed against Slack's real hello; message and app_mention events reached the agent with valid signatures and were acked; a refused event was redelivered by Slack with X-Slack-Retry-Num: 1 and acked on retry; PUT moved delivery to a new forward path; DELETE closed the socket and kept the trigger.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The reviewed update appears safe to merge; no blocking issues remain.

Summary

Adds Slack Socket Mode delivery through a separate bridge process, with encrypted app tokens and routes to manage each trigger’s connection.

  • A separate bridge forwards Slack events to their agent.
  • Slack triggers can switch between HTTP and Socket Mode delivery.

Reviews (15) · Last reviewed commit: "fix(agentex): load the environment befor..." · Reviewed by Greptile

@socket-security

socket-security Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedpypi/​slack-sdk@​3.46.087100100100100

View full report

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

✱ stlc build

✅ python code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅ → lint ✅

234 files generated at e616d35 (pushed)

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅ → build ✅ → lint ✅

133 files generated at ce2c8ef (pushed)

Diagnostics: ⚠️ 3 warning, 💡 39 note
LevelCodeMessageTargets
⚠️ warningTypeScript/PublishingWithoutOIDCPublishing security issue: trusted publishing with OIDC is not enabled.
#/targets/typescript/publish/npm
typescript
⚠️ warningParameter/DuplicateNamesDuplicate parameters were renamed: `name`
(resource) agents.schedules > (method) update_by_name
python
⚠️ warningPython/PublishingWithoutOIDCPublishing security issue: trusted publishing with OIDC is not enabled.
#/targets/python/publish/pypi
python
💡 notePagination/NotConfiguredConfirm your API does not return paginated results.
#/pagination
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/CreateTaskRequest`
#/components/schemas/CreateTaskRequest
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/CancelTaskRequest`
#/components/schemas/CancelTaskRequest
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/InterruptTaskRequest`
#/components/schemas/InterruptTaskRequest
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/SendMessageRequest`
#/components/schemas/SendMessageRequest
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/SendEventRequest`
#/components/schemas/SendEventRequest
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/ScheduleInitialInput`
#/components/schemas/ScheduleInitialInput
typescript, python
💡 noteModel/RecommendedWe recommend you use a model for `#/components/schemas/ScheduleCreatorPrincipal`
#/components/schemas/ScheduleCreatorPrincipal
typescript, python
💡 noteSchema/IsAmbiguousMissing type for schema
#/paths//agents/forward/name/{agent_name}/{path}/get/responses/200/content/application/json/schema
python, typescript
💡 noteSchema/IsAmbiguousMissing type for schema
#/paths//agents/forward/name/{agent_name}/{path}/post/responses/200/content/application/json/schema
python, typescript
…29 more note diagnostics omitted.
Build metadata
Buildbd_76n6bx9W-striped-snow
Timestamp2026-11-19T17:00:21.019Z
stlc667ab50
Spec hash815a0d75203e
Config hashd1f20568f2f4

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-11-19 17:01:01 UTC

Comment thread agentex/src/adapters/orm.py Resolved
@kenairhodesScale
kenairhodesScale marked this pull request as ready for review November 18, 2026 17:42
@kenairhodesScale
kenairhodesScale requested a review from a team as a code owner November 18, 2026 17:42
@kenairhodesScale

Copy link
Copy Markdown
Contributor Author

@greptile

@declan-scale declan-scale left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mostly lgtm, couple things to get it to approved

  1. The generate check fails because there's a merge conflict in the Python SDK. can resolve withstlc build --continue
  2. If possible would be great to do a real test run (I have the golden agent slack test app if you want to use that, shared it with you here)
  3. just want to make sure there is a corresponding bridge deployment pr with:
    • 2 replicas
    • probes on :5004
    • DATABASE_URL and AGENTEX_CREDENTIAL_ENCRYPTION_KEY
    • egress to Slack
    • a network path to the ACP URLs of the agents

@kenairhodesScale

Copy link
Copy Markdown
Contributor Author

@declan-scale

  1. The generate check fails because there's a merge conflict in the Python SDK. can resolve withstlc build --continue

Still having some issues with this one, although it looks like the workflow has been failing for a bit as well https://github.com/scaleapi/scale-agentex/actions/workflows/stlc-generate.yml

  1. If possible would be great to do a real test run (I have the golden agent slack test app if you want to use that, shared it with you here)
Screen.Recording.2026-11-18.at.6.52.31.PM.mov
  1. just want to make sure there is a corresponding bridge deployment pr with:

    • 2 replicas
    • probes on :5004
    • DATABASE_URL and AGENTEX_CREDENTIAL_ENCRYPTION_KEY
    • egress to Slack
    • a network path to the ACP URLs of the agents

infrastructure PR is here https://github.com/scaleapi/sgp/pull/10705

kenairhodesScale and others added 9 commits November 19, 2026 11:48
A Slack app can only push events to a public Request URL, and Slack
publishes no source IP ranges, so an agentex ingress restricted to an
IP allowlist cannot receive them. Socket Mode reverses the direction:
agentex dials out to Slack and receives events over a websocket.

A Slack webhook trigger can now carry an app-level token (xapp-...).
It is stored Fernet-encrypted with the existing credential encryption
key, next to the agent forward path that an HTTP delivery would have
carried in its URL. With SLACK_SOCKET_MODE_ENABLED set, each API
process holds one Socket Mode connection per such trigger, refreshed
every minute, and forwards each events_api envelope to the agent's
forward path with the same body and X-Slack-Retry-* headers. The
envelope is acked only after the agent answers 2xx within 2.5s, so a
failed or slow forward is redelivered by Slack.

A token Slack rejects (revoked, invalid, wrong type) logs one error
and stops that connection instead of looping in slack_sdk's reconnect
retries; it is retried only once the trigger is re-registered. The
bridge refuses to start without the encryption key.

Adds slack-sdk 3.44.1 (aiohttp backend, no optional extras).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Slack caps an app at 10 Socket Mode connections. Holding one per API
uvicorn worker ties the connection count to API scale (replicas times
workers), which can exceed that cap well before the API is large.

The bridge now runs only from src/run_slack_socket_mode_bridge.py, set
up like the Temporal worker (global dependencies, observability, SIGTERM
cancels the main task and unwinds cleanup). Connections per app equal
the number of bridge replicas. The API lifespan no longer starts it, and
SLACK_SOCKET_MODE_ENABLED is gone: running the entrypoint is the switch.

The process serves /healthz and /readyz on port 5004. Readiness only
requires the trigger list to have loaded, so a revoked token does not
take a replica out. On SIGTERM the sockets close first, so Slack moves
delivery to the remaining replicas. Without the credential encryption
key the process logs one error and exits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The earlier lock was re-resolved by a different uv and rewrote platform
markers on every package. Regenerated from main's lock with uv 0.12.12,
which keeps lock revision 3, pinning slack-sdk 3.46.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ck app

- Sign each forwarded event with the trigger's signing secret, so an agent
  that verifies Slack signatures accepts it as it would an HTTP delivery.
- Ack when the agent answers with X-Slack-No-Retry: 1, as over HTTP.
- Keep slack_sdk's rate-limit backoff when opening a connection; only token
  errors that no retry can fix stop the connection.
- Refuse a second Socket Mode trigger for an app another trigger serves, and
  connect only the earliest one if duplicates exist: Slack splits an app's
  events across its connections.
- Start the bridge on one small Postgres engine and an HTTP client instead of
  the API's global dependencies (Temporal, MongoDB, Redis, Kubernetes config),
  so the probe server comes up without waiting on them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dge docs

The new agent_api_keys columns become slack_socket_mode_app_token_encrypted and
slack_socket_mode_forward_path, so the names say what they hold and the ORM
comments go. The migration is unreleased, so it is edited in place.

The docs point to Slack's Socket Mode guide for app setup and drop the
operator notes that restated deployment detail.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agent_api_keys holds one secret per row. The app token and forward path are
a second credential and a routing setting that only some Slack triggers
have, so they move to slack_socket_mode_apps: one row per Slack app, keyed
to its trigger with ON DELETE CASCADE.

A unique constraint on slack_app_id now enforces one owner per app, which
the route's check-then-insert could not under concurrent registrations. The
route maps the violation to the same 409, and the bridge no longer picks a
winner among duplicate triggers. Soft-deleting an agent keeps its keys, so
registration first drops a row left by a deleted agent.

The migration replaces the unreleased add-columns revision under the same id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
slack_sdk's connect() fetches a WebSocket URL once and, if the first
connection attempt fails, retries that same URL forever. Slack issues those
URLs as temporary, so a network error at the wrong moment could leave an app
with no connection until the bridge restarted. Each refresh now reopens a
connection that has not been connected for a whole refresh interval, which
fetches a new URL.

Adds end-to-end tests that run the real route, Postgres and slack_sdk client
against a fake Slack (apps.connections.open plus a Socket Mode WebSocket) and
a fake agent: a delivered event arrives signed and is acked, an event the
agent refuses is acked only on the redelivery it accepts, deleting the
trigger closes the socket, and a connection stuck on a dead URL is reopened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fetching an app's WebSocket URL waits out Slack's Retry-After when the app
is rate-limited. That fetch ran inside refresh(), so one rate-limited app
held up connecting every later app, removing deleted triggers and reopening
stuck connections. It now runs in the app's own connection task, and the
next refresh records a rejected token from the closed client.

The bridge factory moves to the entrypoint, so the domain service no longer
builds database sessions or repositories, and the pool settings are named.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kenairhodesScale and others added 8 commits November 19, 2026 11:48
…sters

The Slack app id is the trigger's name and unique across agents, and
registration only checked the token's xapp- prefix. Any caller who could
update an agent could reserve another team's app with a made-up token, and
the real owner would then get 409.

Registration now opens one Socket Mode connection, reads the app id from
Slack's hello message, and refuses the request unless it matches. A token
Slack rejects returns 400; failing to reach Slack returns 502. The bridge
checks the same field on every connect and closes a connection whose token
belongs to another app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The check that reopens a never-connected app counted from when the
connection opened, so a URL fetch still waiting out a Retry-After longer
than a refresh interval was cancelled and restarted, asking Slack again
sooner than it allowed. The clock now starts when a URL arrives.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
create() registers the key for authorization before inserting it. When the
insert fails, as it now can when two registrations race for one Slack app,
the registration was left behind with no row or id anyone could delete it
by. A failed insert now removes it before the error propagates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the bridge in compose

PUT /agent_api_keys/{id}/slack_socket_mode turns Socket Mode on for an
existing Slack trigger or replaces its app token and forward path, after the
same token checks as registration. DELETE on the same path turns it off and
keeps the trigger. Previously a token could only be changed by deleting and
re-registering the trigger. The bridge now reopens a connection whenever its
row changes, not only its token.

docker compose gains an agentex-slack-socket-bridge service behind the
"slack" profile, and the API and the bridge read
AGENTEX_CREDENTIAL_ENCRYPTION_KEY from the environment, empty by default.
Without the profile nothing changes for make dev.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The python generate step conflicted applying custom code onto this branch's
regenerated SDK. stlc build integrated it locally, pushed the result and its
sealed refs to the python staging repo, and wrote this tracking file so CI
builds from the integrated state instead of hitting the conflict again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…mode

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…utes

The settings routes loaded the key first, so a missing id returned "Item with
id ... does not exist." while a key the caller could not read returned "Agent
api_key not found.", letting a caller tell whether another account's key
exists. They now check access first, as GET /agent_api_keys/{id} does, and map
a failed load to the same message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@declan-scale
declan-scale force-pushed the kenairhodes/slack-socket-mode-bridge branch from 9939260 to 916c3cf Compare November 19, 2026 16:48
In development, EnvironmentVariables.refresh() loads agentex/.env into the
environment. The bridge checked AGENTEX_CREDENTIAL_ENCRYPTION_KEY before that
ran, so a key set only in .env, which the API does pick up, made the bridge
exit and deliver nothing. It now loads the environment first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kenairhodesScale
kenairhodesScale merged commit 703c6a2 into main Nov 19, 2026
49 checks passed
@kenairhodesScale
kenairhodesScale deleted the kenairhodes/slack-socket-mode-bridge branch November 19, 2026 17:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants