@cursor/july 0.1.111 → 0.1.112

package/dist/docs/assets/guides_opentelemetry.md._CRfDyzH.js

@@ -1,26 +0,0 @@
-import{_ as s,c as t,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,d,l,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to &quot;OpenTelemetry&quot;">​</a></h1><p>Agent SDK can push traces, metrics, and logs from the serve process to an OTLP collector you run. Point the process at the collector with standard <code>OTEL_EXPORTER_OTLP_*</code> environment variables, or pass the same options to <code>serve({ otel })</code>. Traces cover the inbound request, each turn, and every tool call.</p><p>Export is opt-in. Nothing leaves the process until you set an endpoint.</p><h2 id="what-does-agent-sdk-export" tabindex="-1">What does Agent SDK export? <a class="header-anchor" href="#what-does-agent-sdk-export" aria-label="Permalink to &quot;What does Agent SDK export?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Signal</th><th>Default</th><th>What you get</th></tr></thead><tbody><tr><td>Traces</td><td>on</td><td><code>agent_sdk.http</code> (per request) and <code>agent_sdk.turn</code> → <code>agent_sdk.tool</code> / <code>agent_sdk.subagent</code></td></tr><tr><td>Metrics</td><td>on</td><td><code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, plus <code>agent_sdk.*</code> session and turn counts</td></tr><tr><td>Logs</td><td>off</td><td>Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in</td></tr></tbody></table><p>Turn off a signal with <code>traces: false</code>, <code>metrics: false</code>, or <code>logs: false</code> on <code>serve({ otel })</code>. Logs also turn on when you set <code>OTEL_LOGS_EXPORTER</code> to anything other than <code>none</code>, or when you set the content flags below.</p><h2 id="how-do-i-turn-opentelemetry-export-on" tabindex="-1">How do I turn OpenTelemetry export on? <a class="header-anchor" href="#how-do-i-turn-opentelemetry-export-on" aria-label="Permalink to &quot;How do I turn OpenTelemetry export on?&quot;">​</a></h2><p>Set a collector URL in the serve process environment:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Authorization=Bearer …&quot;</span></span></code></pre></div><p>The default wire format is OTLP/HTTP protobuf. That matches <a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a>. Set <code>OTEL_EXPORTER_OTLP_PROTOCOL=http/json</code> when your collector only accepts JSON. The runtime accepts <code>http/protobuf</code> and <code>http/json</code>. <code>grpc</code> falls back to protobuf and logs a warning.</p><p><code>OTEL_EXPORTER_OTLP_ENDPOINT</code> is the base URL. The runtime appends <code>/v1/traces</code>, <code>/v1/metrics</code>, and <code>/v1/logs</code>. If you pass a signal path, it is stripped back to the base first.</p><p>To send each signal to a different collector, omit the base URL and set the per-signal vars:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://traces.example.com/v1/traces</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://metrics.example.com/v1/metrics</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://logs.example.com/v1/logs</span></span></code></pre></div><p>Optional:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>OTEL_SERVICE_NAME</code></td><td>Resource <code>service.name</code>. Default <code>cursor</code></td></tr><tr><td><code>OTEL_LOG_USER_PROMPTS=1</code></td><td>Include user prompt text on logs and span events</td></tr><tr><td><code>OTEL_LOG_TOOL_CONTENT=1</code></td><td>Include tool payloads and failure text (truncated)</td></tr></tbody></table><p><code>serve(dir, { otel: false })</code> turns export off even when env is set.</p><p>You can pass the same options object to <code>serve(dir, { otel })</code>. Precedence is <code>serve({ otel })</code> over env.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(dir, {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  otel: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    serviceName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cursor&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    exporters: [</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://otel.example.com&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        protocol: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;http/protobuf&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        headers: { Authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Bearer …&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    ],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Multiple <code>exporters</code> fan out to every destination. Restrict one destination with <code>signals: [&quot;traces&quot;]</code>.</p><p><code>defineOtel</code> / <code>agent/otel.ts</code> (<code>@cursor/july/internal/otel</code>) is factory-only. Discovery still loads that file for Cursor factory agents. It is not a public Agent SDK export.</p><p>The companion skill is <a href="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>.</p><h2 id="what-spans-does-a-session-produce" tabindex="-1">What spans does a session produce? <a class="header-anchor" href="#what-spans-does-a-session-produce" aria-label="Permalink to &quot;What spans does a session produce?&quot;">​</a></h2><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent_sdk.http          inbound channel request (W3C traceparent)</span></span>
-<span class="line"><span>agent_sdk.turn          one root per turn (\`agent_sdk.session_id\` = session id)</span></span>
-<span class="line"><span>  ├─ agent_sdk.tool</span></span>
-<span class="line"><span>  └─ agent_sdk.subagent</span></span>
-<span class="line"><span>       └─ agent_sdk.tool</span></span></code></pre></div><p>Conversational sessions stay on <code>session.waiting</code> and can take more turns, so there is no <code>agent_sdk.session</code> span — it would never end and OTel only exports ended spans. Each turn is its own root. Inbound HTTP is a separate SERVER span (it extracts W3C <code>traceparent</code>) and does not parent the turn, so the turn tree can export when the turn ends. Hosted flush ends that SERVER span before the one-shot export so <code>agent_sdk.http</code> is in the same batch.</p><p>Turns that resume after restore, or a direct <code>callTool</code> with no <code>turn.started</code> in this process, open a synthetic turn span so tool calls still nest.</p><h2 id="which-attributes-land-on-the-wire" tabindex="-1">Which attributes land on the wire? <a class="header-anchor" href="#which-attributes-land-on-the-wire" aria-label="Permalink to &quot;Which attributes land on the wire?&quot;">​</a></h2><p>Every signal carries these resource attributes:</p><ul><li><code>service.name</code> (<code>cursor</code> unless you override it)</li><li><code>cursor.entrypoint=sdk_ts</code></li><li><code>cursor.surface=unspecified</code></li><li><code>agent_sdk.framework=@cursor/july</code></li></ul><p>Span attributes (not process resource attributes — one serve process handles many sessions):</p><ul><li><code>agent_sdk.session_id</code> / <code>cursor.conversation.id</code>: the session id. Search all turns for one conversation with <code>@agent_sdk.session_id</code>.</li></ul><p>Shared names (same keys as enterprise export):</p><ul><li><code>cursor.conversation.id</code>: the session id</li><li><code>cursor.model.name</code></li><li><code>cursor.token.usage</code> with <code>cursor.token.type</code> of <code>input</code>, <code>output</code>, <code>cache_read</code>, <code>cache_creation</code>, or <code>reasoning</code></li><li><code>cursor.tool.calls</code> with <code>cursor.tool.name</code>, <code>cursor.tool.kind</code>, and <code>cursor.tool.status</code></li><li><code>cursor.cost.usage</code> (USD)</li></ul><p>Agent SDK only (<code>agent_sdk.*</code>): session id, agent name, turn id, channel, call id, subagent name, session mode, and HTTP duration (<code>agent_sdk.http.duration</code>).</p><h2 id="how-do-i-emit-my-own-metrics" tabindex="-1">How do I emit my own metrics? <a class="header-anchor" href="#how-do-i-emit-my-own-metrics" aria-label="Permalink to &quot;How do I emit my own metrics?&quot;">​</a></h2><p><code>ctx.host.otel</code> is always present on tools, hooks, and channel handlers. Counters and histograms no-op when no meter is running. <code>setAttributes</code> still tags open turn/tool spans when a collector is attached.</p><p>Prefix metric names with your team or agent. First-party names (<code>cursor.token.usage</code>, <code>cursor.tool.calls</code>, <code>cursor.cost.usage</code>, <code>agent_sdk.session.count</code>, <code>agent_sdk.turn.count</code>, <code>agent_sdk.subagent.count</code>, <code>agent_sdk.http.duration</code>) and join keys (<code>cursor.conversation.id</code>, <code>agent_sdk.session_id</code>, <code>agent_sdk.agent</code>, <code>agent_sdk.turn_id</code>, <code>agent_sdk.framework</code>) are reserved. Custom spans are not on this surface.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;abc.ticket_id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INC-123&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;abc.queue&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;p1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;abc.ticket.resolved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">record</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;abc.approval.duration_ms&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1420</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  outcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;approved&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>A session-bound host (tools and hooks) adds <code>cursor.conversation.id</code> and <code>agent_sdk.agent</code> for you. Tags merge: later <code>setAttributes</code> calls paint open spans and later first-party metrics.</p><h2 id="what-stays-off-the-opentelemetry-wire" tabindex="-1">What stays off the OpenTelemetry wire? <a class="header-anchor" href="#what-stays-off-the-opentelemetry-wire" aria-label="Permalink to &quot;What stays off the OpenTelemetry wire?&quot;">​</a></h2><p>User prompts, tool arguments, tool results, and failure messages are omitted by default. Failure spans still record an error status with a generic message (<code>turn failed</code> / <code>session failed</code>).</p><p>Opt in with <code>OTEL_LOG_USER_PROMPTS=1</code> and <code>OTEL_LOG_TOOL_CONTENT=1</code>, or the matching <code>logs: { userPrompts, toolContent }</code> fields on <code>serve({ otel })</code>. Opted-in strings truncate at 2,048 characters.</p><p>Deployment URLs from <code>agent.bound</code> stay off spans unless <code>toolContent</code> is on.</p><h2 id="how-does-agent-sdk-export-relate-to-cursor-enterprise-export" tabindex="-1">How does Agent SDK export relate to Cursor enterprise export? <a class="header-anchor" href="#how-does-agent-sdk-export-relate-to-cursor-enterprise-export" aria-label="Permalink to &quot;How does Agent SDK export relate to Cursor enterprise export?&quot;">​</a></h2><p><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a> is the team-admin path. Cursor servers send org-wide metrics and logs to a collector you configure in Team Settings.</p><p>Agent SDK export is the process-local path. The serve process sends per-run traces, and optional metrics and logs, to a collector you point it at.</p><p>Point both at the same collector when you want one view. Group on <code>cursor.conversation.id</code>. Resource defaults (<code>service.name=cursor</code>, <code>cursor.entrypoint=sdk_ts</code>) keep the streams next to each other. The <a href="https://cursor.com/docs/enterprise/opentelemetry-export/wire" target="_blank" rel="noreferrer">wire reference</a> lists the shared attribute names.</p><p>Evals (<code>defineEval</code>) stay the in-product regression check. OpenTelemetry is the graph in your observability stack.</p><h2 id="what-if-another-opentelemetry-sdk-is-already-running" tabindex="-1">What if another OpenTelemetry SDK is already running? <a class="header-anchor" href="#what-if-another-opentelemetry-sdk-is-already-running" aria-label="Permalink to &quot;What if another OpenTelemetry SDK is already running?&quot;">​</a></h2><p>OTel providers are process-global. If Cursor CLI, an extension host, or another library already registered a TracerProvider, MeterProvider, or LoggerProvider, Agent SDK reuses it. Run <code>serve</code> as its own process when the Agent SDK exporters should own the destination.</p><p>Two mounts with different authored OTel configs fail at serve start. Configure once through <code>serve({ otel })</code> or env.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><ul><li><a href="./../../skills/otel/SKILL.html"><code>skills/otel/SKILL.md</code></a>: compact env / <code>serve({ otel })</code> reference for coding agents</li><li><a href="./../reference/hooks.html">Hooks</a>: observe the same session event stream in-process</li><li><a href="./../deployment.html">Deployment</a>: env, secrets, and self-hosting</li><li><a href="https://cursor.com/docs/enterprise/opentelemetry-export" target="_blank" rel="noreferrer">Cursor enterprise OpenTelemetry Export</a></li></ul>`,52)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_opentelemetry.md._CRfDyzH.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as t,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run.","frontmatter":{"title":"OpenTelemetry","description":"Push session, turn, and tool traces from the serve process to an OTLP collector you run."},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),n={name:"guides/opentelemetry.md"};function i(r,e,d,l,p,c){return a(),t("div",null,[...e[0]||(e[0]=[o("",52)])])}const u=s(n,[["render",i]]);export{k as __pageData,u as default};

package/dist/docs/assets/guides_slack.md.DdT8rmsj.js

@@ -1,46 +0,0 @@
-import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to &quot;Slack agents&quot;">​</a></h1><p>The Slack channel is a Socket Mode bot. The app connects out, so you don&#39;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.</p><p>Use <code>agent-sdk slack create</code> when Cursor should own the Slack app. Use <code>agent-sdk slack init --manual</code> when you own it. Commands and flags live in the <a href="./../reference/cli.html#slack">CLI reference</a>. Coding agents should follow <a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>.</p><h2 id="define-the-channel" tabindex="-1">Define the channel <a class="header-anchor" href="#define-the-channel" aria-label="Permalink to &quot;Define the channel&quot;">​</a></h2><p>Author <code>agent/channels/slack.ts</code> with <code>slackChannel()</code> from <code>@cursor/july/channels/slack</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels/slack&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p><code>slackChannel()</code> reads <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. Pass <code>envPrefix: &quot;WEATHER_AGENT&quot;</code> to read <code>WEATHER_AGENT_SLACK_BOT_TOKEN</code> and <code>WEATHER_AGENT_SLACK_APP_TOKEN</code> instead. Use a prefix when one host serves several Slack bots.</p><p>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 <code>serve</code> still starts.</p><h2 id="control-who-can-message-the-agent" tabindex="-1">Control who can message the agent <a class="header-anchor" href="#control-who-can-message-the-agent" aria-label="Permalink to &quot;Control who can message the agent&quot;">​</a></h2><p>External senders are blocked. Set <code>blockExternals: false</code> only when people outside your org should reach the agent:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { blockExternals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Anyone in the thread can continue it. Restrict follow-ups to the person who started the session with <code>respondTo: &quot;author&quot;</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  policy: { respondTo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;author&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="choose-how-the-reply-arrives" tabindex="-1">Choose how the reply arrives <a class="header-anchor" href="#choose-how-the-reply-arrives" aria-label="Permalink to &quot;Choose how the reply arrives&quot;">​</a></h2><p>Slack gives an agent two places to show progress while a turn runs: the status chip under the thread (&quot;Running grep…&quot;) and the reply message itself. It won&#39;t fill both at once. While a message is streaming, Slack shows its own &quot;is working…&quot; chip and hides any status text you set. Cards only exist inside a streamed message. <code>reply.mode</code> picks the path.</p><h3 id="post-default-status-chip-then-one-message" tabindex="-1"><code>post</code> (default): status chip, then one message <a class="header-anchor" href="#post-default-status-chip-then-one-message" aria-label="Permalink to &quot;\`post\` (default): status chip, then one message&quot;">​</a></h3><p>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.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;post&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    status: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      reasoning: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      tools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      idle: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Checking the monorepo…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Poking Datadog…&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>idle</code> is the rotation Slack cycles through when nothing more specific is known, up to 5 lines of 50 characters. Pass a function to <code>tools</code> to write your own line from the calls in flight.</p><h3 id="stream-live-text-with-cards" tabindex="-1"><code>stream</code>: live text, with cards <a class="header-anchor" href="#stream-live-text-with-cards" aria-label="Permalink to &quot;\`stream\`: live text, with cards&quot;">​</a></h3><p>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.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stream&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    reasoningCard: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    toolCards: { group: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;per-tool&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  toolLabels: { grep: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Searching code&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, read: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Reading files&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The reasoning card is one task card, titled &quot;Thinking&quot;, that receives the model&#39;s reasoning as it streams and completes when the answer text starts. <code>maxChars</code> (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.</p><p>Tool cards default to one card per tool name with a call count in the title (<code>grep ×3</code>), updated in place as calls finish. <code>group: &quot;per-call&quot;</code> shows one card per call instead.</p><p>Cards are collapsible by default: each call adds one line under the title, the same summary the playground shows in a tool&#39;s header (the grep pattern, the file path, the shell command), and the group expands the same way the reasoning card does. <code>collapsible: false</code> keeps cards to their titles. On a collapsible card, <code>details(call)</code> returns the line to add when a call starts and <code>output(result)</code> the text to add when it finishes.</p><p><code>toolLabels</code> renames tools everywhere they appear: the chip, card titles, and the default <code>Running …</code> line.</p><h3 id="agentic-the-agent-posts" tabindex="-1"><code>agentic</code>: the agent posts <a class="header-anchor" href="#agentic-the-agent-posts" aria-label="Permalink to &quot;\`agentic\`: the agent posts&quot;">​</a></h3><p>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 <code>toolApprovals</code>.</p><p>Mount <code>@cursor/july/extensions/slack-communication</code> so the agent can talk. The extension adds typed tools and the <code>slack-voice</code> skill. The channel watches those tool names (bare or <code>&lt;namespace&gt;__&lt;name&gt;</code>) and calls Slack through the channel client after a successful result. A rejected call, a dry-run stub, or a turn that never calls <code>post-update</code> stays silent. The framework does not also finalize assistant text.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/slack.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> slackCommunication </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions/slack-communication&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackCommunication</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/channels/slack.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agentic&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Tool</th><th>What it writes</th><th>Scope</th></tr></thead><tbody><tr><td><code>post-update</code></td><td>Mid-turn progress and the final reply (<code>chat.postMessage</code> / <code>chat.update</code>)</td><td><code>chat:write</code></td></tr><tr><td><code>post-card</code></td><td>Collapsible task card (<code>chat.startStream</code> / <code>chat.appendStream</code>)</td><td><code>chat:write</code></td></tr><tr><td><code>post-file</code></td><td>Workspace file on the reply (<code>files.getUploadURLExternal</code>)</td><td><code>files:write</code></td></tr><tr><td><code>react</code></td><td>Emoji on a message <code>ts</code> (<code>reactions.add</code>). Omit <code>ts</code> for the thread root.</td><td><code>reactions:write</code></td></tr><tr><td><code>set-status</code></td><td>Subtitle chip (<code>assistant.threads.setStatus</code>). Empty string clears it.</td><td><code>assistant:write</code></td></tr></tbody></table><p><code>agent-sdk slack create</code> already grants those scopes. Do not add a freeform Slack method tool.</p><p>Pass <code>tone</code> to add agent-specific voice without forking the tools:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackCommunication</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tone: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Lead with the merge decision. Name the risk next.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="migrating-from-streaming-and-thinkingsteps" tabindex="-1">Migrating from <code>streaming</code> and <code>thinkingSteps</code> <a class="header-anchor" href="#migrating-from-streaming-and-thinkingsteps" aria-label="Permalink to &quot;Migrating from \`streaming\` and \`thinkingSteps\`&quot;">​</a></h3><p><code>streaming: false</code> is <code>reply: { mode: &quot;post&quot; }</code>. <code>streaming: true</code> is <code>reply: { mode: &quot;stream&quot;, toolCards: { group: &quot;per-call&quot;, collapsible: false } }</code>, the title-only cards it used to show. <code>loadingMessages</code> moves to <code>reply.status.idle</code>. The old options still work and <code>agent-sdk validate</code> prints the rewrite for each one.</p><p>A channel that set none of these used to stream. It now posts. Set <code>reply: { mode: &quot;stream&quot; }</code> to keep streaming.</p><h2 id="set-it-up" tabindex="-1">Set it up <a class="header-anchor" href="#set-it-up" aria-label="Permalink to &quot;Set it up&quot;">​</a></h2><p><code>slack create</code> opens the Cursor dashboard wizard. Finish Slack consent and the bot name there. The CLI writes tokens to <code>.env.local</code> and never prints them. Skip the wizard if those tokens are already set, unless you want a Cursor-managed app.</p><h3 id="provision-with-the-cli" tabindex="-1">Provision with the CLI <a class="header-anchor" href="#provision-with-the-cli" aria-label="Permalink to &quot;Provision with the CLI&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span></span></code></pre></div><p>Sign in first (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). A team service-account key cannot create Slack apps. Finish <strong>Add Slack to this agent</strong> as the same Cursor account. Then run <code>agent-sdk slack doctor --prefix MY_AGENT</code> and serve:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><p>Invite the bot and mention it, or DM it. Expect a Thinking status, then a threaded streaming reply.</p><p>If Slack needs a workspace admin, keep the CLI running. Open the <strong>Request approval</strong> link it prints. After an admin approves, click <strong>Retry</strong> in the wizard.</p><p><code>slack destroy</code> deletes the Cursor-managed app. <code>slack icon</code> updates its icon. A second <code>slack create</code> for the same agent and environment replaces that app&#39;s manifest and tokens.</p><h3 id="provision-from-the-dashboard" tabindex="-1">Provision from the dashboard <a class="header-anchor" href="#provision-from-the-dashboard" aria-label="Permalink to &quot;Provision from the dashboard&quot;">​</a></h3><p>The same wizard is on <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">Deployed Agents</a>. Open <strong>Integrations</strong> and click <strong>Add Slack to this agent</strong>.</p><p>Local <code>agent-sdk serve</code> reads <code>.env.local</code>. The next deploy injects the stored secrets.</p><p>If Slack needs admin approval, click <strong>Request approval</strong>, then <strong>Retry</strong> after an admin approves.</p><p>The app row&#39;s menu covers rename, icon, token rotation, removal, and workspace disconnect.</p><h3 id="create-your-own-slack-app" tabindex="-1">Create your own Slack app <a class="header-anchor" href="#create-your-own-slack-app" aria-label="Permalink to &quot;Create your own Slack app&quot;">​</a></h3><p><code>slack init --manual</code> is for an app you own. It writes the channel file and Slack manifests. When Slack CLI (<code>~/.slack/bin/slack</code>) is logged in, it installs the app. When it isn&#39;t, install the app yourself.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --manual</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --name</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;My Agent&quot;</span></span></code></pre></div><p>Install Slack CLI if you need it:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -fsSL</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://downloads.slack-edge.com/slack-cli/install.sh</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bash</span></span></code></pre></div><p>Log in with <code>slack login --no-prompt</code>. In Slack, send <code>/slackauthticket &lt;ticket&gt;</code>, then <code>slack login --ticket &lt;ticket&gt; --challenge &lt;code&gt;</code>. Install the workspace app with <code>slack app install</code>. Create a separate production app the same way.</p><p>Or paste <code>.slack/manifest.dev.json</code> at <a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">api.slack.com/apps</a> (<strong>Create New App</strong> → <strong>From a manifest</strong>). Repeat with <code>.slack/manifest.prod.json</code>. Dev and prod are separate Slack apps.</p><p>Then put a bot token (<code>xoxb-...</code>) and an app-level token with <code>connections:write</code> (<code>xapp-...</code>) in <code>.env.local</code>. Use the names <code>slack init --manual</code> printed. Run <code>slack doctor</code> and serve as above.</p><p>Serve this app with Agent SDK. Do not run <code>slack deploy</code>.</p><h2 id="choose-when-the-agent-engages" tabindex="-1">Choose when the agent engages <a class="header-anchor" href="#choose-when-the-agent-engages" aria-label="Permalink to &quot;Choose when the agent engages&quot;">​</a></h2><p>Mentions and DMs are on. Watching channel posts without a mention is opt-in:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TRIAGE&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  engagement: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    channelPosts: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;#triage-alerts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      posts: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;top-level&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      debounceMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">15_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onChannelPost</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message.markdown.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 20</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Pass <code>--channel-posts</code> on <code>slack create</code> or <code>slack init --manual</code> so the Slack app receives those events. The bot must be in each watched channel. <code>allow: [&quot;*&quot;]</code> watches every joined channel.</p><p>Set <code>includeBotPosts: true</code> for alert feeds and other bots. This app never wakes on its own posts.</p><h2 id="prepare-work-on-the-host" tabindex="-1">Prepare work on the host <a class="header-anchor" href="#prepare-work-on-the-host" aria-label="Permalink to &quot;Prepare work on the host&quot;">​</a></h2><p>Mention and DM handlers may return a prepared <code>message</code>, <code>workspaceFiles</code>, or <code>cloud</code> block. Use the same host-prep pattern as <a href="./webhooks.html#prepare-on-the-host-then-hand-off">custom channels</a>.</p><p>Slack file uploads attach automatically. Images become vision input. Supported documents become workspace files for the turn.</p><h2 id="add-approval-buttons" tabindex="-1">Add approval buttons <a class="header-anchor" href="#add-approval-buttons" aria-label="Permalink to &quot;Add approval buttons&quot;">​</a></h2><p>Tools with <code>needsApproval</code> park until a person decides. Post those decisions in Slack with one flag:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  toolApprovals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The Slack app needs interactivity. Recreate it with <code>slack create</code> 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 <a href="./../reference/tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>.</p><h2 id="run-several-agents-on-one-host" tabindex="-1">Run several agents on one host <a class="header-anchor" href="#run-several-agents-on-one-host" aria-label="Permalink to &quot;Run several agents on one host&quot;">​</a></h2><p>Give each agent its own Slack app and token pair. Set <code>envPrefix</code> so the names don&#39;t collide (<code>WEATHER_AGENT_SLACK_*</code>, <code>TRIAGE_SLACK_*</code>). Agents without tokens stay idle. The others still serve.</p>`,75)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/guides_slack.md.DdT8rmsj.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own.","frontmatter":{"title":"Slack","description":"Run a Socket Mode Slack bot from the dashboard wizard, or import an app you own."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,o,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[t("",75)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};