Repository navigation
feat(agentex): deliver Slack webhook triggers over Socket Mode - #486
Conversation
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
✱ stlc build✅ python code · compare
✅ typescript code · compare
Diagnostics:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Level | Code | Message | Targets |
|---|---|---|---|
TypeScript/PublishingWithoutOIDC | Publishing security issue: trusted publishing with OIDC is not enabled.#/targets/typescript/publish/npm | typescript | |
Parameter/DuplicateNames | Duplicate parameters were renamed: `name`(resource) agents.schedules > (method) update_by_name | python | |
Python/PublishingWithoutOIDC | Publishing security issue: trusted publishing with OIDC is not enabled.#/targets/python/publish/pypi | python | |
| 💡 note | Pagination/NotConfigured | Confirm your API does not return paginated results.#/pagination | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/CreateTaskRequest`#/components/schemas/CreateTaskRequest | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/CancelTaskRequest`#/components/schemas/CancelTaskRequest | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/InterruptTaskRequest`#/components/schemas/InterruptTaskRequest | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/SendMessageRequest`#/components/schemas/SendMessageRequest | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/SendEventRequest`#/components/schemas/SendEventRequest | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/ScheduleInitialInput`#/components/schemas/ScheduleInitialInput | typescript, python |
| 💡 note | Model/Recommended | We recommend you use a model for `#/components/schemas/ScheduleCreatorPrincipal`#/components/schemas/ScheduleCreatorPrincipal | typescript, python |
| 💡 note | Schema/IsAmbiguous | Missing type for schema#/paths//agents/forward/name/{agent_name}/{path}/get/responses/200/content/application/json/schema | python, typescript |
| 💡 note | Schema/IsAmbiguous | Missing 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
| Build | bd_76n6bx9W-striped-snow |
| Timestamp | 2026-11-19T17:00:21.019Z |
| stlc | 667ab50 |
| Spec hash | 815a0d75203e |
| Config hash | d1f20568f2f4 |
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
declan-scale
left a comment
There was a problem hiding this comment.
mostly lgtm, couple things to get it to approved
- The
generatecheck fails because there's a merge conflict in the Python SDK. can resolve withstlc build --continue - 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)
- 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
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
Screen.Recording.2026-11-18.at.6.52.31.PM.mov
infrastructure PR is here https://github.com/scaleapi/sgp/pull/10705 |
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>
…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>
…branch" This reverts commit d67521a.
…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>
9939260 to
916c3cf
Compare
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>
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-triggertakes an optionalapp_token(xapp-…). Registration checks with Slack that the token belongs to the app inname, then stores it encrypted in a newslack_socket_mode_appstable, one row per app.python -m src.run_slack_socket_mode_bridge, holds one socket per app and POSTs each event to the agent'sforward_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_modeswitches an existing Slack trigger to Socket Mode or replaces its token and path;DELETEon the same path turns it off.AGENTEX_CREDENTIAL_ENCRYPTION_KEY. New dependency:slack-sdk.AGENTEX_CREDENTIAL_ENCRYPTION_KEY=... docker compose --profile slack-socket-mode upalso 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) endA 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 endTesting
hello;messageandapp_mentionevents reached the agent with valid signatures and were acked; a refused event was redelivered by Slack withX-Slack-Retry-Num: 1and acked on retry;PUTmoved delivery to a new forward path;DELETEclosed the socket and kept the trigger.🤖 Generated with Claude Code


Confidence 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.
Reviews (15) · Last reviewed commit: "fix(agentex): load the environment befor..." · Reviewed by Greptile