@cursor/july 0.1.96 → 0.1.97

package/dist/docs/guides/slack.md

@@ -1,15 +1,13 @@
 # Slack agents
 
-The Slack channel puts your agent in Slack as its own Socket Mode bot.
-`agent-sdk slack create` opens the dashboard wizard and writes tokens
-to `.env.local`. To own the Slack app yourself, run
-`agent-sdk slack init --manual` and paste the manifests at
-[api.slack.com](https://api.slack.com/apps). Socket Mode has no
-public Request URL. Replies stream in threads, with tool "thinking" steps,
-suggested prompts, and opt-in approval buttons.
+The Slack channel is a Socket Mode bot. The app connects out, so you
+don't need a public Request URL. Mentions and DMs start a thread.
+Replies stream there, with thinking steps and suggested prompts.
 
-The companion skill is
-[`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
+Use `agent-sdk slack create` when Cursor should own the Slack app. Use
+`agent-sdk slack init --manual` when you own it. Commands and flags live
+in the [CLI reference](/docs/reference/cli.md#slack). Coding agents should
+follow [`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md).
 
 ## Define the channel
 
@@ -19,35 +17,23 @@ Author `agent/channels/slack.ts` with `slackChannel()` from
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN
 export default slackChannel();
-
-// Multi-agent serve: one Slack app (and token pair) per agent
-export default slackChannel({ envPrefix: "WEATHER_AGENT" });
-// → WEATHER_AGENT_SLACK_BOT_TOKEN + WEATHER_AGENT_SLACK_APP_TOKEN
 ```
 
-By default the channel connects over Socket Mode (the app connects
-outward, so it works from behind any firewall) and responds only to
-`app_mention` events and direct messages. It also refuses Slack Connect
-users, guests, and senders from other workspaces. Threads bind to
-sessions with `continuationToken = channelId:threadTs`, so a thread is
-one durable conversation. Replies stream (`chat.startStream` /
-`appendStream` / `stopStream`) with a plain-message fallback, a rotating
-status shows while the agent works, and the pack sets thread titles and
-suggested prompts. When a Slack API is unavailable (`method_not_found`,
-`missing_scope`), the pack degrades to `postMessage` instead of failing.
-
-Missing tokens leave the channel idle (`channel idle … missing
-credentials`) rather than failing `serve`. That's useful when you mount
-many agents and only some have Slack apps.
+`slackChannel()` reads `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN`. Pass
+`envPrefix: "WEATHER_AGENT"` to read `WEATHER_AGENT_SLACK_BOT_TOKEN`
+and `WEATHER_AGENT_SLACK_APP_TOKEN` instead. Use a prefix when one
+host serves several Slack bots.
+
+A thread is one conversation. The bot answers mentions and DMs. It
+refuses Slack Connect users, guests, and people from other workspaces.
+Missing tokens leave this channel idle. The rest of `serve` still
+starts.
 
 ## Control who can message the agent
 
-External senders are blocked by default. Slack Connect users, guests, and
-people whose home workspace is not the install team never reach the
-handler. Set `blockExternals: false` only when the agent should serve
-people outside your org:
+External senders are blocked. Set `blockExternals: false` only when
+people outside your org should reach the agent:
 
 ```ts
 export default slackChannel({
@@ -55,9 +41,8 @@ export default slackChannel({
 });
 ```
 
-Sessions are thread-scoped by default, so anyone in the thread can
-continue. Restrict follow-ups to the person who started the session with
-`respondTo: "author"`:
+Anyone in the thread can continue it. Restrict follow-ups to the person
+who started the session with `respondTo: "author"`:
 
 ```ts
 export default slackChannel({
@@ -67,234 +52,140 @@ export default slackChannel({
 
 ## Set it up
 
-For a dedicated Socket Mode bot, run `agent-sdk slack create`. The CLI
-opens the signed-in Cursor dashboard wizard. Slack consent, bot name,
-and admin-approval wait happen there. Tokens are stored as deployment
-secrets and written to `.env.local`. They are never shown. Do not paste
-a manifest at [api.slack.com](https://api.slack.com/apps) unless you
-are on the [manual setup](#manual-setup) path.
-
-Bots that already have tokens in `.env.local` keep working. Skip the
-wizard unless you want a Cursor-managed app.
+`slack create` opens the Cursor dashboard wizard. Finish Slack consent
+and the bot name there. The CLI writes tokens to `.env.local` and never
+prints them. Skip the wizard if those tokens are already set, unless
+you want a Cursor-managed app.
 
 ### Provision with the CLI
 
 ```bash
-agent-sdk slack create --dir .          # dev app (default)
-agent-sdk slack create --dir . --prod   # prod app
+agent-sdk slack create --dir .
+agent-sdk slack create --dir . --prod
 ```
 
-`slack create` needs a signed-in host (`agent-sdk login` or
-`CURSOR_API_KEY`). It scaffolds `agent/channels/slack.ts` when the file
-is missing, opens the dashboard wizard, and waits. Finish **Add Slack
-to this agent** in the browser as the same Cursor account. The CLI
-writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
-`<dir>/.env.local`, then runs `doctor`. Serve and smoke it as described
-[below](#wire-the-env-and-verify).
-
-If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request. Open Slack's
-**Request approval** page (the CLI prints the link; the same URL is
-**Send a reminder** after you submit). After an admin approves, click
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Slack to this agent** as the same Cursor account. Then run
+`agent-sdk slack doctor --prefix MY_AGENT` and serve:
+
+```bash
+agent-sdk serve --dir . --dev
+```
+
+Invite the bot and mention it, or DM it. Expect a Thinking status,
+then a threaded streaming reply.
+
+If Slack needs a workspace admin, keep the CLI running. Open the
+**Request approval** link it prints. After an admin approves, click
 **Retry** in the wizard.
 
-Useful companions: `--name` / `--icon` / `--channel-posts` prefill the
-wizard. `--slack-team T0123ABCD` picks a workspace when several are
-connected. A second `slack create` for the same agent and env overwrites
-that Slack app. It keeps the Slack app id and replaces the manifest and
-tokens. `agent-sdk slack destroy` deletes the provisioned app.
-`agent-sdk slack icon <source>` updates the icon later.
+`slack destroy` deletes the Cursor-managed app. `slack icon` updates
+its icon. A second `slack create` for the same agent and environment
+replaces that app's manifest and tokens.
 
 ### Provision from the dashboard
 
 The same wizard is on [Deployed Agents](https://cursor.com/dashboard).
-Open **Integrations** on an agent and click **Add Slack to this agent**,
-or follow the URL `slack create` printed.
+Open **Integrations** and click **Add Slack to this agent**.
 
-A first-run agent that has no hosted engine yet shows **Not deployed
-yet**. Local `agent-sdk serve` works from `.env.local`. The next
-**Deploy** injects the stored secrets; there is no Slack-only Redeploy.
+Local `agent-sdk serve` reads `.env.local`. The next deploy injects the
+stored secrets.
 
-If Slack needs admin approval, the wizard waits. Click **Request
-approval** to file the request in Slack (that same page later sends a
-reminder). After an admin approves, click **Retry**.
+If Slack needs admin approval, click **Request approval**, then
+**Retry** after an admin approves.
 
-The app row's menu covers later care: rename, set an icon, rotate
-tokens, remove the app, or disconnect the workspace.
+The app row's menu covers rename, icon, token rotation, removal, and
+workspace disconnect.
 
-### Wire the env and verify
+### Create your own Slack app
 
-`agent-sdk slack create` already wrote the tokens to `.env.local`, so
-after provisioning skip straight to `doctor`. `serve` / `dev` /
-`slack doctor` load that file (real environment variables always win).
+`slack init --manual` is for an app you own. It writes the channel file
+and Slack manifests. When Slack CLI (`~/.slack/bin/slack`) is logged
+in, it installs the app. When it isn't, install the app yourself.
 
 ```bash
-agent-sdk slack doctor --prefix MY_AGENT
-```
-
-Proceed when `app_token`, `connections_open`, `bot_token`, and
-`auth_test` are all green. Then serve and smoke it:
-
-```bash
-agent-sdk serve --dir . --dev
-# expect: [agent-sdk/slack] Socket Mode connected
+agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-Invite the bot to a channel and @mention it (or DM it). Expect the
-Thinking… status, then a threaded streaming reply, with correlated
-server logs (`inbound kind=app_mention`, `session start`,
-`reply delivered via stream|postMessage`).
-
-### Manual setup
-
-`slack init --manual` is for a Slack app you own at api.slack.com. You
-paste the generated manifests and mint tokens yourself. Use this when
-you want an unmanaged app, or when the dashboard wizard is not an
-option.
+Install Slack CLI if you need it:
 
 ```bash
-agent-sdk slack init --manual --dir . --name "My Agent"
+curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
 ```
 
-That writes `agent/channels/slack.ts`, Slack manifests under the
-project state directory, `env.example`, and `setup-status.json`.
-`--no-prefix` uses shared `SLACK_*` variables on
-a single-agent host. `--prefix CUSTOM` overrides the directory-derived
-prefix. `--channel-posts` subscribes the manifests to channel-post
-events.
+Log in with `slack login --no-prompt`. In Slack, send
+`/slackauthticket <ticket>`, then
+`slack login --ticket <ticket> --challenge <code>`. Install the
+workspace app with `slack app install`. Create a separate production
+app the same way.
 
-`slack manifest --env both` regenerates the JSON files without
-touching the channel file.
+Or paste `.slack/manifest.dev.json` at
+[api.slack.com/apps](https://api.slack.com/apps) (**Create New App** →
+**From a manifest**). Repeat with `.slack/manifest.prod.json`. Dev and
+prod are separate Slack apps.
 
-#### Create the apps
+Then put a bot token (`xoxb-...`) and an app-level token with
+`connections:write` (`xapp-...`) in `.env.local`. Use the names
+`slack init --manual` printed. Run `slack doctor` and serve as above.
 
-This phase needs someone with permission to create Slack apps.
-
-1. Open [api.slack.com/apps](https://api.slack.com/apps) → **Create New
-   App** → **From a manifest**.
-2. Paste `manifest.dev.json` and create the dev app.
-3. Repeat with `manifest.prod.json`. Dev and prod are separate Slack
-   apps with separate tokens.
-
-#### Install and mint tokens
-
-For each app: **Install to Workspace** and copy the Bot User OAuth Token
-(`xoxb-…`). Then under **Basic Information → App-Level Tokens** create a
-token with scope `connections:write` and copy it (`xapp-…`).
-
-Put the pair in `.env.local` using the names from `env.example`, then
-run `slack doctor` and serve as [above](#wire-the-env-and-verify).
+Serve this app with Agent SDK. Do not run `slack deploy`.
 
 ## Choose when the agent engages
 
-Mentions and DMs are on by default. Watching channels means dispatching
-on new posts without a mention. That's an explicit opt-in:
+Mentions and DMs are on. Watching channel posts without a mention is
+opt-in:
 
 ```ts
 export default slackChannel({
   envPrefix: "TRIAGE",
   engagement: {
-    // mentions / directMessages default to true
     channelPosts: {
-      allow: ["#triage-alerts"], // use ["*"] for every joined channel
-      posts: "top-level",       // default: thread replies never dispatch
-      debounceMs: 15_000,       // optional: let rapid edits settle
-      includeBotPosts: false,   // default: bot-authored posts never dispatch
+      allow: ["#triage-alerts"],
+      posts: "top-level",
+      debounceMs: 15_000,
     },
   },
-  onChannelPost: async (ctx, message) => {
-    // same contract as onAppMention: return null to skip
+  onChannelPost: async (_ctx, message) => {
     return message.markdown.length > 20 ? {} : null;
   },
 });
 ```
 
-Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app. Pass `--channel-posts` on `slack create` or
-`slack init --manual`. The bot must also be a member of each watched
-channel.
-
-Set `allow: ["*"]` to watch every channel the bot has joined.
+Pass `--channel-posts` on `slack create` or `slack init --manual` so
+the Slack app receives those events. The bot must be in each watched
+channel. `allow: ["*"]` watches every joined channel.
 
-Set `includeBotPosts: true` when the posts worth watching come from bots:
-alert feeds, webhook integrations, or other agents posting notes. The
-watching app's own posts stay dropped either way, matched by the `bot_id`
-and bot user id from `auth.test`, so an agent can never dispatch on its
-own replies. Use this for a bot-fed alerts channel.
+Set `includeBotPosts: true` for alert feeds and other bots. This app
+never wakes on its own posts.
 
 ## Prepare work on the host
 
 Mention and DM handlers may return a prepared `message`,
-`workspaceFiles`, or `cloud` block. It's the same host-prep pattern as
+`workspaceFiles`, or `cloud` block. Use the same host-prep pattern as
 [custom channels](/docs/guides/webhooks.md#prepare-on-the-host-then-hand-off).
-PR agents use it: extract a PR URL from the mention text and run the
-same host path as the HTTP channel.
 
-Slack file uploads are attached automatically. Images become vision input.
+Slack file uploads attach automatically. Images become vision input.
 Supported documents become workspace files for the turn.
 
 ## Add approval buttons
 
-Tools with `needsApproval` park until a person decides. Route that
-through Slack with one flag:
+Tools with `needsApproval` park until a person decides. Post those
+decisions in Slack with one flag:
 
 ```ts
 export default slackChannel({
-  toolApprovals: true, // posts Block Kit Approve/Deny cards + routes clicks
+  toolApprovals: true,
 });
 ```
 
-Approval cards need interactivity on the Slack app. Recreate with
-`slack create` if clicks do nothing. Composing events by hand: spread
-`buildToolApprovalEvents({ credentials })` into `events` and set
-`interactivity: true` on the channel so Socket Mode routes the clicks.
-
-Cards show redacted, truncated arguments (Block Kit size limits);
-execution still uses the full validated input, so review sensitive tools
-in the playground when the arguments may exceed the card. Approvals
-exist for `execution: "server"` tools on the local runtime only, and
-parked calls do not survive a host restart. The full lifecycle is in
+The Slack app needs interactivity. Recreate it with `slack create` if
+clicks do nothing. Cards show redacted, truncated arguments. Execution
+still uses the full input, so review sensitive tools in the playground
+when the card may hide fields. The lifecycle is in
 [Human-in-the-loop](/docs/guides/human-in-the-loop.md).
 
 ## Run several agents on one host
 
-One Slack app and token pair per agent. Never share a pair across
-agents in the same process. `envPrefix` keeps them apart
-(`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`, …), and agents without tokens mount
-with their Slack channel idle while everything else serves normally.
-
-## Keep the channel healthy
-
-Two habits matter most.
-
-- Don't `await` long work inside Slack dispatch handlers. The pack
-  dispatches through `waitUntil` and streams as the turn progresses.
-- In `--dev` (loopback) or `--allow-anonymous` (trusted shared host), the
-  playground can list and stream Slack sessions and resolve their parked
-  approvals (the audit trail records the HTTP caller). Bearer-auth hosts
-  stay strict: Slack approvals must come from Slack interactivity or a
-  matching principal.
-
-## CLI reference
-
-The `slack` subcommands cover setup end to end.
-
-```bash
-agent-sdk slack setup                     # printed setup guide
-agent-sdk slack create --dir .            # dashboard wizard (dev app)
-agent-sdk slack create --dir . --prod     # prod app
-agent-sdk slack destroy --dir .           # delete the provisioned app
-agent-sdk slack icon ./icon.png --dir .   # set the provisioned app's icon
-agent-sdk slack init --manual --dir .     # manifests to paste at api.slack.com
-agent-sdk slack manifest --env both       # regenerate those JSON files
-agent-sdk slack doctor --prefix MY_AGENT  # token / connectivity checks
-```
-
-## What's next
-
-Continue with these pages:
-
-- [Human-in-the-loop](/docs/guides/human-in-the-loop.md): the approval lifecycle
-  behind `toolApprovals`
-- [Webhooks and custom channels](/docs/guides/webhooks.md): the mechanism this
-  pack is built on
+Give each agent its own Slack app and token pair. Set `envPrefix` so
+the names don't collide (`WEATHER_AGENT_SLACK_*`, `TRIAGE_SLACK_*`).
+Agents without tokens stay idle. The others still serve.