@cursor/july 0.1.111 → 0.1.113

package/dist/docs/guides/slack.md

@@ -1,320 +1,250 @@
 # Slack agents
 
-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 land in that thread. You choose the status chip, a live
-stream, or agent-owned posts.
+A Slack agent wakes when someone mentions it, sends it a DM, or posts
+in a channel it watches. From there, it keeps the conversation in one
+thread and can reply all at once, stream the answer live, or decide for
+itself when to post updates.
 
-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).
+Run `agent-sdk slack create --dir .`, then `agent-sdk slack doctor`.
 
-## Define the channel
+## Answer a mention or DM
 
-Author `agent/channels/slack.ts` with `slackChannel()` from
-`@cursor/july/channels/slack`:
+Mention the bot in a channel or send it a DM, and it will answer in a
+thread on that message. Any follow-up in the same thread continues the
+conversation where it left off.
 
 ```ts
+// agent/channels/slack.ts
 import { slackChannel } from "@cursor/july/channels/slack";
 
-export default slackChannel();
-```
-
-`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. Set `blockExternals: false` only when
-people outside your org should reach the agent:
-
-```ts
 export default slackChannel({
-  policy: { blockExternals: false },
-});
-```
-
-Anyone in the thread can continue it. Restrict follow-ups to the person
-who started the session with `respondTo: "author"`:
-
-```ts
-export default slackChannel({
-  policy: { respondTo: "author" },
+  // TRIAGE_SLACK_BOT_TOKEN and TRIAGE_SLACK_APP_TOKEN
+  envPrefix: "TRIAGE",
 });
 ```
 
-## Choose how the reply arrives
-
-Slack gives an agent two places to show progress while a turn runs: the
-status chip under the thread ("Running grep…") and the reply message
-itself. It won't fill both at once. While a message is streaming, Slack
-shows its own "is working…" chip and hides any status text you set. Cards
-only exist inside a streamed message. `reply.mode` picks the path.
-
-### `post` (default): status chip, then one message
+## Post one reply with a status chip
 
-Tool calls and the first line of each reasoning block show in the chip as
-they happen. The answer lands as a single message when the turn finishes.
+By default, Slack shows a status chip beneath the thread while the turn
+runs, cycling through idle messages until reasoning or tool activity
+gives it something more specific to show. When the turn finishes, the
+chip disappears and one complete reply lands in the thread.
 
 ```ts
 export default slackChannel({
   reply: {
     mode: "post",
     status: {
+      // First line of each reasoning block on the chip.
       reasoning: true,
+      // Tool names as they start ("Running grep, glob...").
       tools: true,
-      idle: ["Checking the monorepo…", "Poking Datadog…"],
+      idle: ["Checking the monorepo...", "Poking Datadog..."],
     },
   },
 });
 ```
 
-`idle` is the rotation Slack cycles through when nothing more specific is
-known, up to 5 lines of 50 characters. Pass a function to `tools` to write
-your own line from the calls in flight.
+## Stream a live reply
 
-### `stream`: live text, with cards
-
-The answer streams into one message as the model writes it. Slack owns the
-chip for the duration, so live feedback inside the message comes from
-cards. Both are off unless you turn them on.
+In stream mode, the reply appears immediately and grows as the model
+writes. Slack shows its generic "is working..." state until the stream
+ends, while optional reasoning and tool cards keep progress inside the
+same message.
 
 ```ts
 export default slackChannel({
   reply: {
     mode: "stream",
+    // Thinking card inside the streamed message.
     reasoningCard: true,
-    toolCards: { group: "per-tool" },
+    // One card per tool in that same message.
+    toolCards: true,
   },
-  toolLabels: { grep: "Searching code", read: "Reading files" },
 });
 ```
 
-The reasoning card is one task card, titled "Thinking", that receives the
-model's reasoning as it streams and completes when the answer text starts.
-`maxChars` (default 1500) caps how much it collects. Slack caps a streamed
-message near 12k characters including cards; when an answer outgrows that,
-the streamed message closes where it stands and the rest continues in a
-new message.
-
-Tool cards default to one card per tool name with a call count in the title
-(`grep ×3`), updated in place as calls finish. `group: "per-call"` shows one
-card per call instead.
-
-Cards are collapsible by default: each call adds one line under the title,
-the same summary the playground shows in a tool's header (the grep pattern,
-the file path, the shell command), and the group expands the same way the
-reasoning card does. `collapsible: false` keeps cards to their titles. On a
-collapsible card, `details(call)` returns the line to add when a call starts
-and `output(result)` the text to add when it finishes.
-
-`toolLabels` renames tools everywhere they appear: the chip, card titles,
-and the default `Running …` line.
-
-### `agentic`: the agent posts
-
-Opt in when the agent should own every message in the thread. Mentions
-and DMs still start turns. The channel does not write the status chip,
-tool cards, reasoning cards, or assistant text. Approval cards
-still post if you set `toolApprovals`.
-
-Mount `@cursor/july/extensions/slack-communication` so the agent can
-talk. The extension adds typed tools and the `slack-voice` skill. The
-channel watches those tool names (bare or `<namespace>__<name>`) and
-calls Slack through the channel client after a successful result. A
-rejected call, a dry-run stub, or a turn that never calls
-`post-update` stays silent. The framework does not also finalize
-assistant text.
+## Let the agent own every message
+
+Use agentic mode when the agent should decide how to communicate, not
+only what to say. The bot reacts to the parent message with eyes and
+shows a thinking chip, then the agent chooses when to post progress and
+how to deliver the final reply.
+
+`slack-communication` gives those posts a Slack-aware voice by default:
+lead with the result, share progress when the picture changes, and keep
+tool chatter off the thread. Use `tone` for the rest of the
+communication contract, including voice, level of detail, formatting,
+and how updates should be structured.
 
 ```ts
 // agent/extensions/slack.ts
 import slackCommunication from "@cursor/july/extensions/slack-communication";
 
-export default slackCommunication();
+export default slackCommunication({
+  tone:
+    "Be concise but warm. Use bullets for evidence and end with the next action.",
+});
 ```
 
 ```ts
-// agent/channels/slack.ts
 export default slackChannel({
+  // `post-update` writes mid-turn progress and the final reply.
   reply: { mode: "agentic" },
 });
 ```
 
-| Tool | What it writes | Scope |
-| --- | --- | --- |
-| `post-update` | Mid-turn progress and the final reply (`chat.postMessage` / `chat.update`) | `chat:write` |
-| `post-card` | Collapsible task card (`chat.startStream` / `chat.appendStream`) | `chat:write` |
-| `post-file` | Workspace file on the reply (`files.getUploadURLExternal`) | `files:write` |
-| `react` | Emoji on a message `ts` (`reactions.add`). Omit `ts` for the thread root. | `reactions:write` |
-| `set-status` | Subtitle chip (`assistant.threads.setStatus`). Empty string clears it. | `assistant:write` |
-
-`agent-sdk slack create` already grants those scopes. Do not add a
-freeform Slack method tool.
+## Wake on a channel post
 
-Pass `tone` to add agent-specific voice without forking the tools:
+This example watches `#triage-alerts`, so any substantial top-level
+message starts a thread even when nobody mentions the bot. The length
+guard filters out short posts before they can start a turn.
 
 ```ts
-export default slackCommunication({
-  tone: "Lead with the merge decision. Name the risk next.",
+export default slackChannel({
+  engagement: {
+    channelPosts: {
+      allow: ["#triage-alerts"],
+      posts: "top-level",
+      debounceMs: 15_000,
+    },
+  },
+  onChannelPost: async (_ctx, message) => {
+    if (message.markdown.length <= 20) {
+      return null;
+    }
+    // `{}` starts a model turn as the sender.
+    return {};
+  },
 });
 ```
 
-### Migrating from `streaming` and `thinkingSteps`
+When you create the app, pass `--channel-posts` and invite the bot to
+every channel in the allowlist.
 
-`streaming: false` is `reply: { mode: "post" }`. `streaming: true` is
-`reply: { mode: "stream", toolCards: { group: "per-call", collapsible:
-false } }`, the title-only cards it used to show. `loadingMessages` moves
-to `reply.status.idle`. The old options still work and `agent-sdk validate`
-prints the rewrite for each one.
+## Control who can message
 
-A channel that set none of these used to stream. It now posts. Set
-`reply: { mode: "stream" }` to keep streaming.
+By default, people outside your workspace get no reply. This matters
+most in Slack Connect channels, where external collaborators share the
+channel and can mention or reply to bots installed by your
+organization. Keeping `blockExternals` on prevents them from starting
+or steering an agent session and, through it, directing any tools
+available to the agent.
 
-## Set it up
+Set `blockExternals: false` only when external collaborators are
+intended users of the agent.
 
-`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 .
-agent-sdk slack create --dir . --prod
+```ts
+export default slackChannel({
+  // Let external collaborators start and continue agent sessions.
+  policy: { blockExternals: false },
+});
 ```
 
-Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). A team
-service-account key cannot create Slack apps. Finish **Add
-Slack to this agent** as the same Cursor account. Then run
-`agent-sdk slack doctor --prefix MY_AGENT` and serve:
+Anyone in a thread can continue its session by default. If the
+conversation should stay between the agent and its original author,
+set `respondTo: "author"`.
 
-```bash
-agent-sdk serve --dir . --dev
+```ts
+export default slackChannel({
+  policy: { respondTo: "author" },
+});
 ```
 
-Invite the bot and mention it, or DM it. Expect a Thinking status,
-then a threaded streaming reply.
+## Events
 
-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.
+Mentions and DMs wake the agent automatically, while `onChannelPost`
+runs for messages in watched channels. Declare `onAppMention` or
+`onDirectMessage` when you need to filter those default wakes; each
+handler returns `{}` to start a turn or `null` to skip it.
 
-`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.
+For example, this handler only starts a turn for DMs prefixed with
+`triage:`:
 
-### Provision from the dashboard
+```ts
+onDirectMessage: async (_ctx, message) => {
+  if (!message.markdown.startsWith("triage:")) {
+    return null;
+  }
+  // `{}` starts a model turn as the sender.
+  return {};
+},
+```
 
-The same wizard is on [Deployed Agents](https://cursor.com/dashboard).
-Open **Integrations** and click **Add Slack to this agent**.
+## Thread affinity
 
-Local `agent-sdk serve` reads `.env.local`. The next deploy injects the
-stored secrets.
+A Slack thread maps to one agent session, so every follow-up in that
+thread resumes the same conversation.
 
-If Slack needs admin approval, click **Request approval**, then
-**Retry** after an admin approves.
+## Call Slack from deterministic code via `ctx`
 
-The app row's menu covers rename, icon, token rotation, removal, and
-workspace disconnect.
+Channel hooks can post before starting the model turn, which is useful
+for deterministic acknowledgements such as `Looking at this now.` The
+same bot credential also lets tools call Slack later in the turn:
 
-### Create your own Slack app
+- Channel hooks: `ctx.thread.post()`, `ctx.slack.channelId`,
+  `ctx.slack.threadTs`
 
-`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.
+- Tools: `ctx.host.slack.getClient()`
 
-```bash
-agent-sdk slack init --manual --dir . --name "My Agent"
+```ts
+onAppMention: async (ctx, message) => {
+  if (message.markdown.trim() === "") {
+    return null;
+  }
+  await ctx.thread.post("Looking at this now.");
+  return {};
+},
 ```
 
-Install Slack CLI if you need it:
+Use the IDs on the hook `ctx` when handling an event, and
+`ctx.host.slack.getClient()` when a tool needs the Slack Web API.
+
+## Connect
 
 ```bash
-curl -fsSL https://downloads.slack-edge.com/slack-cli/install.sh | bash
+agent-sdk login
+agent-sdk slack create --dir .
+agent-sdk slack doctor --prefix TRIAGE
 ```
 
-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.
-
-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.
+After you sign in, `slack create` opens **Add Slack to this agent** in
+the browser and writes the resulting tokens to `.env.local` without
+printing them. You can open the same wizard from **Integrations** on
+[Deployed Agents](https://cursor.com/dashboard).
 
-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.
+If you already own the Slack app, initialize it with
+`agent-sdk slack init --manual --dir . --name "Triage"` and follow the
+[Slack setup skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md) for installation
+and tokens.
 
-Serve this app with Agent SDK. Do not run `slack deploy`.
+## Test locally
 
-## Choose when the agent engages
+Run `doctor` first to catch missing credentials, then start the agent
+and send it the same mention or DM a teammate would.
 
-Mentions and DMs are on. Watching channel posts without a mention is
-opt-in:
-
-```ts
-export default slackChannel({
-  envPrefix: "TRIAGE",
-  engagement: {
-    channelPosts: {
-      allow: ["#triage-alerts"],
-      posts: "top-level",
-      debounceMs: 15_000,
-    },
-  },
-  onChannelPost: async (_ctx, message) => {
-    return message.markdown.length > 20 ? {} : null;
-  },
-});
+```bash
+agent-sdk slack doctor --prefix TRIAGE
+agent-sdk serve --dir . --dev
 ```
 
-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` 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. Use the same host-prep pattern as
-[custom channels](/docs/guides/webhooks.md#prepare-on-the-host-then-hand-off).
-
-Slack file uploads attach automatically. Images become vision input.
-Supported documents become workspace files for the turn.
+## Practices
 
-## Add approval buttons
+- If the tokens are missing, the Slack channel stays idle while the
+  rest of `serve` starts normally.
 
-Tools with `needsApproval` park until a person decides. Post those
-decisions in Slack with one flag:
-
-```ts
-export default slackChannel({
-  toolApprovals: true,
-});
-```
+- Keep `channelPosts.allow` narrow because each qualifying post can
+  start a model turn.
 
-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
-[Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval).
+- Set `envPrefix` when two Slack bots share a host so the token names
+  do not collide.
 
-## Run several agents on one host
+## Related
 
-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.
+- [CLI reference](/docs/reference/cli.md#slack): `slack create`,
+  `doctor`, `init --manual`
+- [`skills/setup-slack/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md):
+  the companion skill for coding agents
+- [Webhooks and custom channels](/docs/guides/webhooks.md): host prep on mention
+  and DM handlers
+- [Evals](/docs/evals.md): freeze a mention as a regression check