Slack Integration

@Polarity in any channel — investigate traces, debug behaviors, ship fixes without leaving Slack.

Install the Polarity Slack app and @Polarity becomes a participant in your team's existing debugging conversations. It has the same access as the Paragon Agent in the dashboard: traces, judges, behaviors, datasets. Same brain, new surface.

The integration is two pieces:

@Polarity in channels — natural-language investigation
Alert delivery — behavior automations can post to Slack channels when conditions fire

What it looks like

sarah: @Polarity why did the agent give a full refund on order #9384?

@Polarity: The agent triggered the refund_full tool despite the customer
only asking for partial credit. Root cause: the classify_intent span
returned refund_full because the phrase "give my money back" maps to
full refund in the current rubric.

This pattern has occurred 142 times in the last 7 days, totaling
$6,800 in over-refunds across 89 affected customers.

[View traces] [View behavior]

The bot replies in-thread. Follow-up mentions in the same Slack thread continue the same Paragon conversation — context carries across messages.

Install

There's no install flow from the dashboard yet, but it's a two-step OAuth.

1. Get a workspace install URL

Hit the install-url endpoint with your Polarity API key:

curl -s https://api.plr.sh/v1/slack/install-url \
  -H "Authorization: Bearer $POLARITY_API_KEY"
# → {"url": "https://slack.com/oauth/v2/authorize?..."}

2. Open the URL in a browser

Slack prompts you to choose the workspace and approve the requested scopes. Click Allow.

You land on a ?slack=installed confirmation page. Behind the scenes a row is written to keystone_slack_workspaces mapping your Slack workspace → your Polarity org. The bot is now in your workspace.

3. Invite the bot to a channel

In Slack:

/invite @Polarity

Now @Polarity is mentionable from that channel.

Bot scopes

The Polarity Slack app requests:

Scope	Why
`app_mentions:read`	See when someone says `@Polarity`
`chat:write`	Post replies
`chat:write.public`	Reply in channels the bot isn't a member of
`commands`	Reserved for future slash commands
`users:read`	Map Slack users → Polarity users for attribution
`channels:history`	Read recent messages when investigating context

No private DM access. No file scope. No admin scope. The bot only sees channels you invite it to.

Thread persistence

Each Slack thread maps 1:1 to a Paragon thread:

First @Polarity mention → new Paragon thread, tagged with metadata.slack_key = "<team>:<channel>:<thread_ts>"
Subsequent mentions in the same thread → resume the same Paragon thread, with full transcript context
The thread also appears in the dashboard at /judgement-agent?thread=<id> so you can keep investigating from the web UI if you prefer

Architecture

The Slack integration is a thin adapter on top of the existing Paragon Agent:

Slack Events API
       │  (app_mention)
       ▼
api.plr.sh/v1/slack/events
       │
       ▼
Paragon Agent loop  ←─ same code path as /judgement-agent
       │
       ▼
Block Kit renderer  →  Slack chat.postMessage

Slack adds zero new tools. The bot's capabilities are exactly the Paragon Agent's capabilities, rendered as Slack messages instead of dashboard blocks.

Configuration

Server-side env vars (set on the Polarity API server):

Env var	Purpose
`SLACK_CLIENT_ID`	From Slack app Basic Information
`SLACK_CLIENT_SECRET`	From Slack app Basic Information
`SLACK_SIGNING_SECRET`	From Slack app Basic Information
`SLACK_REDIRECT_URL`	OAuth callback — typically `https://api.plr.sh/v1/slack/oauth/callback`
`SLACK_INSTALL_SUCCESS_URL`	(optional) Where users land after `Allow` — default is a plain JSON 200
`SLACK_STATE_SECRET`	(optional) HMAC key for OAuth state — falls back to `SLACK_SIGNING_SECRET`

These are platform-side; end users don't set anything.

Endpoints

Method + Path	Purpose	Auth
`GET /v1/slack/install-url`	Returns a signed-state Slack OAuth URL	Polarity API key
`GET /v1/slack/oauth/callback`	Called by Slack after consent; UPSERTs the workspace	Slack OAuth state
`POST /v1/slack/events`	Receives Slack events (URL verification + app_mention)	Slack signing secret

The events endpoint verifies X-Slack-Signature (HMAC-SHA256 over v0:ts:body) with a 5-minute replay window. The OAuth state is an HMAC-signed token with a 15-minute expiry.

Alert delivery

Independent of the bot, the Slack integration enables Slack as an Alerts action:

WHEN  behavior "Helpful Refund Response" = false
AND   trace.llm_cost > $0.01
THEN  post to Slack #agent-alerts
AND   add to dataset "regression-suite"

Configure the destination channel in the alert rule. Messages use Slack's standard chat.postMessage format with deep-links back to the dashboard.

Troubleshooting

Symptom	Likely cause
Bot doesn't reply to `@Polarity`	Bot isn't invited to the channel (`/invite @Polarity`)
Bot replies "I hit an error setting up this conversation"	Workspace row missing — re-run the install flow
Bot replies "Hey — ask me about a trace, behavior…"	Your `@Polarity` mention had no text after it
Slack reports "request_url did not respond with HTTP 200"	`SLACK_SIGNING_SECRET` mismatch, or the server isn't reachable from Slack
OAuth callback returns "invalid state"	State expired (15-min TTL) or `SLACK_STATE_SECRET` changed between install and callback

Next steps

Paragon Agent — the brain behind @Polarity; same capabilities, dashboard surface
Alerts — route behavior failures to Slack automatically
Behaviors — the labels Slack alerts fire on

Paragon Agent Prompts