feat(agentex): run Slack turns as the invoking user, and the flow to link them

[michael-chou359]

What

Part of the event-driven agents work, and the half of it that changes behavior.
#409 added storage for linking an external chat identity to an SGP user; nothing
consumed it. This wires it up and adds the flow that creates the links.

Before this, every Slack-originated turn ran as a single shared bot service account.
The agent acted with one fixed identity regardless of who asked, and its tools could
only ever reach what that bot could reach. After this, when the person who sent the
message has linked their account, the turn runs as them — so their own connected
integrations (Notion, Linear, …) resolve.

Unlinked users are unaffected. No link means the existing bot path, unchanged.

The linking flow

The mapping can't be derived — nothing in a webhook says anything about SGP. So it's
established in the one moment where both identities are authenticated at once, with a
server-side nonce tying two requests together.

1.  Slack event arrives
      Slack's HMAC proves the Slack side — only Slack could have signed it.
      We hold a trusted (team_id, user_id) and no idea who that is in SGP.
               │
2.  park it in a nonce → single-use, short TTL          link_nonce_service
      {provider, team_id, external_user_id, display_name, pending_turn}
      The browser receives only an opaque token.
               │
3.  user clicks → GET /integrations/slack/link?nonce=…  integrations.py
      NOT auth-whitelisted (unlike /slack), so the auth middleware runs and
      the user's own browser session supplies the SGP side.
               │
4.  both halves in ONE request → confirmation page naming each identity
               │
5.  POST → mint a key as that user  → encrypt + store → burn the nonce
               │
6.  every later event: resolve → decrypt → forward      slack_gateway_use_case
      the agent's tools now act as that person

Why a nonce rather than ids in the URL. A query string is user-editable. Given
?slack_user=<someone else>, an attacker could click their own link while signed in as
themselves and bind that person's chat identity to their own SGP account — after
which the victim's messages would run as the attacker, using the attacker's
integrations, with the victim's prompts landing in the attacker's account. An opaque
token means nothing in the URL is meaningful, so nothing in it is forgeable.

Change

Gateway (slack_gateway_use_case.py)

• _turn_identity() resolves (team, user) → link → that user's principal and acting
  headers. Falls back to the bot when there's no usable link.
• Task naming is now per-user for linked users (slack:{thread_ts}:{sgp_user_id}), so
  two people in one thread don't write into a shared task. Unlinked users keep the
  legacy key, so existing threads keep their history.
• slack_user_id / sgp_user_id recorded in task_metadata for attribution.

Link flow (new)

• link_nonce_service.py — create / peek / consume. peek is non-consuming so a
  refresh or a link-prefetching browser doesn't burn the nonce; consume is GETDEL,
  so single-use is enforced by Redis rather than by a read-then-delete race. Requires
  Redis and raises rather than degrading — a nonce store that silently forgets would
  turn into "linking randomly fails."

  At most one live nonce per identity. A nonce is a bearer token, so several live
  ones means several chances for a link to be redeemed by the wrong person — and
  consuming one doesn't invalidate its siblings, so a user who linked successfully
  would still have working tokens pointing at their Slack identity until each expired.
  create() therefore invalidates whatever nonce the identity already held, and
  create_or_reuse() re-sends the live link rather than minting a parallel one.
  claim_send() caps DMs about a given link at 2 (IDENTITY_LINK_MAX_DMS), resetting
  whenever a genuinely new nonce is minted so a new link is never withheld.

  Reuse deliberately does not extend the TTL — otherwise mentioning the agent every
  few minutes keeps one token alive indefinitely, and the bounded lifetime is the point.
  The pending turn is refreshed within the remaining window, so linking answers what
  the user most recently asked.

• integrations.py — the two routes and the confirmation page. Deliberately under
  /integrations, not /slack: the latter is auth-whitelisted because Slack's
  signature is its auth, and a callback placed there would run unauthenticated, which
  defeats the whole mechanism.

• adapter_identity_service.py — mints the user's key.

• identity_link_service.py — cached resolution; uncached credential access.

Details that are easy to get wrong

• Two API-key issuers exist and only one works. identity-service mints ssk_
  keys, which sgp-secrets accepts; egp-api-backend mints keys that authenticate fine
  against their own issuer and then fail at the vault with an opaque 401. Storing the
  wrong kind produces a link that looks healthy and silently reads nothing, so the
  client refuses anything not ssk_-shaped rather than discovering it mid-turn.
• Minting needs the user's cookie, not an API key. POST /api-keys is guarded by a
  JWT-cookie guard that rejects x-api-key. That's why the browser leg is load-bearing
  and can't be scripted away — see the testing note below.
• The identity-service URL has no default. It's deployment-specific, and a wrong
  default would POST a user's forwarded session credentials at whatever answers. Unset
  raises.
• acting_headers() is never cached, though resolution is (with a shorter TTL for
  negative results). Caching a credential is how you end up serving a revoked one.
• Every "can't act as them" case returns None, not a partial identity, so the
  gateway falls back explicitly instead of half-assuming a user.
• The nonce is consumed only after a successful store, so a transient failure leaves
  the link clickable instead of sending the user back to Slack for a new one.
• A missing encryption key returns 503 and stores nothing, rather than 500-ing straight
  after minting a real credential.

What this does NOT do

Nothing sends anyone a link. On an unlinked mention the gateway still runs as the
bot; it doesn't offer to connect. Step 1 above has no trigger, so today the flow is
only reachable through scripts/dev_seed_link_nonce.py. The DM trigger —
conversations.open + chat.postMessage, an ephemeral in-channel notice, and replaying
the stashed pending_turn after linking — is the next change. claim_send() is the
primitive it will call; nothing calls it yet.

Also still open, and worth settling in that PR rather than here: the confirmation page
is currently the only thing preventing someone from forwarding their own link to
another person, who could then click through and bind the sender's chat identity to
their own SGP account. The page names both identities, which covers a mis-click but
reduces to user vigilance against a deliberate attempt. Comparing the Slack account's
email against the SGP session's email would close it properly — the storage already has
IdentityLinkMethod.EMAIL_MATCH for exactly this.

So this PR is safe to merge but not yet user-visible, and not yet reachable in a way
that would expose the above.

Testing

• 86 new unit tests — 75 across four new files (link service, nonce service,
  identity-service client, routes) and 11 added to the gateway suite; 156 collected
  across the five touched files. Full CI green (770 unit, 162 integration); ruff clean.

• Coverage is aimed at the failure modes rather than the happy path: wrong-issuer key
  refused, unauthenticated caller mints nothing, expired/stale nonce refused, failed
  mint leaves the nonce intact, SGP account already linked to a different Slack user,
  unconfigured encryption key reported as 503 rather than 500, and the nonce token
  leaking nothing identifying.

• For the nonce specifically: supersede-on-recreate, per-identity isolation (including
  the same user in two workspaces), TTL non-extension on reuse, pending-turn refresh
  with and without KEEPTTL, a stale pointer to a vanished nonce, a pointer corrupted
  to name a different identity's live token, the send cap and its reset, and repair of
  a counter left without an expiry by a crash between INCR and EXPIRE.

• 14 integration tests against a real Redis. The unit tests above use a
  hand-written fake, so they assert our model of Redis rather than Redis — and where
  the model is wrong, they pass while production breaks. These cover the divergences
  that matter: the app runs decode_responses=False so real Redis returns bytes
  where the fake returns str (an undecoded pointer read would silently mint parallel
  tokens); GETDEL atomicity under five concurrent consumes; KEEPTTL genuinely
  preserving an expiry while rewriting the payload — which the fake cannot prove at
  all, and which the "reuse must not extend the lifetime" guarantee rests on; and
  INCR/EXPIRE/TTL returning what the send cap assumes.

  These depend only on redis_url, not isolated_repositories, so they need no
  Postgres or MongoDB — which keeps them at ~3s and runnable where the Mongo image
  won't boot. Verified locally against real Redis, stable across three runs.

⚠️ The live mint is unverified. POST /api-keys requires a genuine browser session,
so no test can stand in for it — everything up to the mint and everything after it is
covered, but the call itself has only been exercised against a stub. It needs one manual
pass against a deployed host before the DM trigger makes this reachable.

For the record: local integration tests error at fixture setup for want of a working
Docker socket. That reproduces identically on a clean checkout of main, so it's
environmental and not from this change; CI runs them.

Deploy notes

• AGENTEX_CREDENTIAL_ENCRYPTION_KEY must be set, or linking returns 503 (by design —
  it will not store a credential in plaintext).
• IDENTITY_SERVICE_URL must be set, or minting raises. No default, deliberately.
• The agentex host must be a sibling subdomain of the SGP host, or the session cookie
  never arrives and step 3 can't resolve anyone.

🤖 Generated with Claude Code

Greptile Summary

This PR adds authenticated Slack-to-SGP identity linking and runs linked Slack turns using each invoking user's principal and delegated credential.

• Adds a Redis-backed, expiring nonce flow and authenticated confirmation routes.
• Mints, encrypts, stores, resolves, and delegates user credentials.
• Separates linked-user task histories and records Slack/SGP attribution metadata.

Confidence Score: 2/5

The PR does not appear safe to merge until nonce redemption gates credential creation and linked task names uniquely scope each Slack conversation.

Concurrent confirmations can still mint and persist credentials before either request claims the nonce, and task names can still merge unrelated Slack conversations that share a timestamp and linked SGP user.

Files Needing Attention: agentex/src/api/routes/integrations.py; agentex/src/domain/use_cases/slack_gateway_use_case.py

Important Files Changed

Filename	Overview
agentex/src/api/routes/integrations.py	Adds the authenticated confirmation and credential-minting flow; the previously reported late nonce claim remains outstanding.
agentex/src/domain/services/link_nonce_service.py	Adds opaque Redis nonce creation, reuse, expiry, send limiting, and atomic consumption primitives.
agentex/src/domain/services/identity_link_service.py	Adds cached identity resolution and uncached credential retrieval for delegated turns.
agentex/src/adapters/identity_service/adapter_identity_service.py	Adds a constrained identity-service client for minting expiring user-owned credentials.
agentex/src/domain/use_cases/slack_gateway_use_case.py	Runs linked turns under invoking-user identities, but the previously reported globally colliding task key remains outstanding.

Sequence Diagram

sequenceDiagram
  participant Slack
  participant Nonce as Redis nonce store
  participant Browser
  participant AgentEx
  participant Identity as Identity service
  participant DB as Identity-link store
  participant Agent

  Slack->>Nonce: Park verified Slack identity
  Nonce-->>Browser: Opaque link token
  Browser->>AgentEx: GET link confirmation with SGP session
  AgentEx->>Nonce: Peek token
  AgentEx-->>Browser: Show Slack and SGP identities
  Browser->>AgentEx: POST confirmation
  AgentEx->>Identity: Mint user-owned API key
  Identity-->>AgentEx: One-time secret
  AgentEx->>DB: Encrypt and store identity link
  AgentEx->>Nonce: Consume token
  Slack->>AgentEx: Later Slack turn
  AgentEx->>DB: Resolve linked user and credential
  AgentEx->>Agent: Dispatch with user principal and delegation headers

Loading

_{Reviews (3): Last reviewed commit: "test(agentex): nonce integration tests a..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Service API and authentication
• Knowledge Base — Task creation and state management
• Knowledge Base — Agent access and API keys

[github-actions]

✱ Stainless preview builds

This PR will update the agentex-sdk SDKs with the following commit messages.

openapi

feat(api): add slack link endpoints and request body to integrations

python

chore(internal): regenerate SDK with no functional changes

typescript

chore(internal): regenerate SDK with no functional changes

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ agentex-sdk-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ✅

New diagnostics (4 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /integrations/slack/link`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /integrations/slack/link`

✅ agentex-sdk-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ⏭️ → lint ⏭️ → test ✅

New diagnostics (4 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /integrations/slack/link`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /integrations/slack/link`

✅ agentex-sdk-python studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ⏭️ (prev: build ✅) → lint ⏭️ (prev: lint ✅) → test ✅

New diagnostics (4 note)

💡 Schema/IsAmbiguous: Missing type for schema

💡 Schema/IsAmbiguous: Missing type for schema

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `get /integrations/slack/link`

💡 Endpoint/NotConfigured: Skipped endpoint because it's not in your Stainless config: `post /integrations/slack/link`

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-25 22:16:17 UTC

[greptile-apps]

Nonce claimed after key minting

If two submissions of the same nonce overlap, both can pass peek() and mint durable API keys before either request consumes the nonce. The losing request can then fail during persistence or overwrite the first link, leaving an untracked key with no revocation path and potentially returning a server error.

How this was verified: The route mints and stores the key before calling the atomic nonce-consumption operation, and it ignores the consumption result.

Prompt To Fix With AI

This is a comment left during a code review.
Path: agentex/src/api/routes/integrations.py
Line: 202-208

Comment:
**Nonce claimed after key minting**

If two submissions of the same nonce overlap, both can pass `peek()` and mint durable API keys before either request consumes the nonce. The losing request can then fail during persistence or overwrite the first link, leaving an untracked key with no revocation path and potentially returning a server error.

**How this was verified:** The route mints and stores the key before calling the atomic nonce-consumption operation, and it ignores the consumption result.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Task key omits Slack scope

If the same linked SGP user has threads with the same timestamp in different Slack workspaces or channels, this globally reused name resolves both turns to one task. The later turn can therefore mix prompts, metadata, agent configuration, and account context into an unrelated Slack conversation.

Knowledge Base Used: Task creation and state management

Prompt To Fix With AI

This is a comment left during a code review.
Path: agentex/src/domain/use_cases/slack_gateway_use_case.py
Line: 764-766

Comment:
**Task key omits Slack scope**

If the same linked SGP user has threads with the same timestamp in different Slack workspaces or channels, this globally reused name resolves both turns to one task. The later turn can therefore mix prompts, metadata, agent configuration, and account context into an unrelated Slack conversation.

**Knowledge Base Used:** [Task creation and state management](https://app.greptile.com/scale-ai/-/custom-context/knowledge-base/scaleapi/scale-agentex/-/docs/task-creation-and-state.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.