@cursor/july 0.1.49 → 0.1.52

package/dist/docs/assets/{guides_slack.md.zriQpU_9.js → guides_slack.md.D2nTRu9M.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Slack","description":"Put the agent in Slack over Socket Mode: Add to Slack provisioning, manifests, tokens, doctor, engagement rules, access policy, and approval buttons.","frontmatter":{"title":"Slack","description":"Put the agent in Slack over Socket Mode: Add to Slack provisioning, manifests, tokens, doctor, engagement rules, access policy, and approval buttons."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function h(l,s,o,p,r,d){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 puts your agent in Slack over Socket Mode: no public Request URL, streaming replies in threads, tool &quot;thinking&quot; steps, suggested prompts, and opt-in approval buttons. Cursor&#39;s <strong>Add to Slack</strong> provisioning handles the setup in one CLI command or one dashboard click; the manual manifest flow remains as a fallback.</p><p>The companion skill is <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>
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Slack","description":"Put the agent in Slack: Cursor-hosted connection or a dedicated Socket Mode app via the dashboard wizard, plus doctor, engagement rules, access policy, and approval buttons.","frontmatter":{"title":"Slack","description":"Put the agent in Slack: Cursor-hosted connection or a dedicated Socket Mode app via the dashboard wizard, plus doctor, engagement rules, access policy, and approval buttons."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function h(l,s,o,p,r,d){return i(),a("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 puts your agent in Slack. Two products: the Cursor-hosted connection (<code>cursorAccount: true</code>), or a dedicated Socket Mode app created in the dashboard wizard (<code>agent-sdk slack create</code>). Socket Mode has no public Request URL. Replies stream in threads, with tool &quot;thinking&quot; steps, suggested prompts, and opt-in approval buttons.</p><p>The companion skill is <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:#6A737D;--shiki-dark:#6A737D;">// Single agent: reads SLACK_BOT_TOKEN + SLACK_APP_TOKEN</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>
@@ -15,9 +15,8 @@ import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <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>Sessions are thread-scoped by default, so anyone in the thread can continue. 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="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>Start with Cursor&#39;s <strong>Add to Slack</strong> provisioning: Cursor creates and installs a dedicated Slack app for the agent and delivers its tokens, so nobody visits <a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">api.slack.com</a> or copies an <code>xoxb-…</code> / <code>xapp-…</code> pair by hand. Use the CLI for local development and the dashboard for hosted deployments. Fall back to the <a href="#manual-setup-fallback">manual manifest flow</a> only when provisioning reports the feature is not enabled for your account.</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><p>One command runs the whole setup:</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;"> 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:#6A737D;--shiki-dark:#6A737D;">          # dev app (default)</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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # prod app</span></span></code></pre></div><p><code>slack create</code> needs a signed-in host (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). It scaffolds <code>agent/channels/slack.ts</code> when the file is missing, connects your Slack workspace through a browser consent page when it isn&#39;t connected yet (a one-time authorization per user and workspace), creates and installs the agent&#39;s dedicated Socket Mode app, writes <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> into <code>&lt;dir&gt;/.env.local</code>, and finishes with a <code>doctor</code> pass. Then serve and smoke it as described <a href="#wire-the-env-and-verify">below</a>; the tokens are already in place.</p><p>If the workspace requires admin approval for new apps, <code>create</code> prints the Slack approval page for a workspace admin. Re-run <code>agent-sdk slack create</code> after the approval to finish the install and mint the tokens.</p><p>Useful companions: <code>--slack-team T0123ABCD</code> picks a workspace when several are connected, <code>--icon &lt;https-url-or-file&gt;</code> sets the app icon, <code>agent-sdk slack destroy</code> deletes the provisioned app, and <code>agent-sdk slack icon &lt;source&gt;</code> updates the icon later. A re-run of <code>create</code> refuses to overwrite manifest edits made by hand in Slack; pass <code>--force</code> to overwrite them.</p><h3 id="provision-from-the-dashboard-hosted-deployments" tabindex="-1">Provision from the dashboard (hosted deployments) <a class="header-anchor" href="#provision-from-the-dashboard-hosted-deployments" aria-label="Permalink to &quot;Provision from the dashboard (hosted deployments)&quot;">​</a></h3><p>For a <a href="./../deployment.html#cursor-managed-hosting">Cursor-hosted deployment</a>, provision from <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>: open <strong>Deployed Agents</strong>, select the deployment, switch to the <strong>Details</strong> view, and expand the <strong>Slack</strong> row under <strong>Integrations</strong>.</p><ol><li>Click <strong>Add to Slack</strong> and approve the authorization in the tab that opens. This is a one-time consent per user and workspace.</li><li>Pick the bot name (and the workspace, when several are connected) and click <strong>Create Slack app</strong>. Cursor creates and installs the app, then stores its tokens as deployment secrets; the values are never shown. The <strong>Advanced</strong> disclosure sets the env-var prefix, so the secret names match what your <code>slackChannel({ envPrefix })</code> reads.</li><li>If the workspace requires admin approval, the row shows <strong>Waiting for admin approval</strong> with an <strong>Approve in Slack</strong> button that opens Slack&#39;s pending-request page. After an admin approves, pick <strong>Retry</strong> from the row&#39;s menu.</li><li>Click <strong>Redeploy</strong> when the banner appears. The running agent keeps its old environment until the next deploy.</li></ol><p>The row&#39;s menu also covers later care: rename the app, set its icon, rotate its tokens, remove it from Slack, or disconnect the workspace.</p><h3 id="manual-setup-fallback" tabindex="-1">Manual setup (fallback) <a class="header-anchor" href="#manual-setup-fallback" aria-label="Permalink to &quot;Manual setup (fallback)&quot;">​</a></h3><p>When Add to Slack is not enabled for your account, create the apps by hand. Generate the channel file, the app manifests, and the env template:</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;"> --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>This writes <code>agent/channels/slack.ts</code> (with an <code>envPrefix</code> derived from the directory name), importable app manifests at <code>.agent-serve/slack/manifest.{dev,prod}.json</code>, and <code>.agent-serve/slack/env.example</code>. Use <code>--no-prefix</code> for the shared <code>SLACK_*</code> variables on single-agent hosts, <code>--prefix CUSTOM</code> to override, and <code>--channel-posts</code> if you plan to watch channels.</p><h4 id="create-the-apps-human-slack-admin" tabindex="-1">Create the apps (human, Slack admin) <a class="header-anchor" href="#create-the-apps-human-slack-admin" aria-label="Permalink to &quot;Create the apps (human, Slack admin)&quot;">​</a></h4><p>This phase needs a human with permission to create Slack apps.</p><ol><li>Open <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>.</li><li>Paste <code>manifest.dev.json</code> and create the dev app.</li><li>Repeat with <code>manifest.prod.json</code>. Dev and prod are separate Slack apps with separate tokens.</li></ol><h4 id="install-and-mint-tokens-human" tabindex="-1">Install and mint tokens (human) <a class="header-anchor" href="#install-and-mint-tokens-human" aria-label="Permalink to &quot;Install and mint tokens (human)&quot;">​</a></h4><p>For each app: <strong>Install to Workspace</strong> and copy the Bot User OAuth Token (<code>xoxb-…</code>), then under <strong>Basic Information → App-Level Tokens</strong> create a token with scope <code>connections:write</code> and copy it (<code>xapp-…</code>).</p><h3 id="wire-the-env-and-verify" tabindex="-1">Wire the env and verify <a class="header-anchor" href="#wire-the-env-and-verify" aria-label="Permalink to &quot;Wire the env and verify&quot;">​</a></h3><p><code>agent-sdk slack create</code> already wrote the tokens to <code>.env.local</code>, so after provisioning skip straight to <code>doctor</code>. After a manual setup, export the tokens in the shell that runs <code>serve</code>, using the names from <code>env.example</code>, or put them in the agent directory&#39;s <code>.env.local</code> — <code>serve</code>/<code>dev</code>/<code>slack doctor</code> load that file (real environment variables always win over 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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> MY_AGENT_SLACK_BOT_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">xoxb-…</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> MY_AGENT_SLACK_APP_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">xapp-…</span></span></code></pre></div><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;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> MY_AGENT</span></span></code></pre></div><p>Proceed when <code>app_token</code>, <code>connections_open</code>, <code>bot_token</code>, and <code>auth_test</code> are all green. Then serve and smoke 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;">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>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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>For a dedicated Socket Mode bot, run <code>agent-sdk slack create</code>. 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 <code>.env.local</code>. They are never shown. Do not paste a manifest at <a href="https://api.slack.com/apps" target="_blank" rel="noreferrer">api.slack.com</a>. <code>slack init</code> is removed.</p><p>Bots that already have tokens in <code>.env.local</code> keep working. Skip the wizard 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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # dev app (default)</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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # prod app</span></span></code></pre></div><p><code>slack create</code> needs a signed-in host (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). It scaffolds <code>agent/channels/slack.ts</code> when the file is missing, opens the dashboard wizard, and waits. Finish <strong>Add Slack to this agent</strong> in the browser as the same Cursor account. The CLI writes <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> into <code>&lt;dir&gt;/.env.local</code>, then runs <code>doctor</code>. Serve and smoke it as described <a href="#wire-the-env-and-verify">below</a>.</p><p>If Slack needs a workspace admin to approve the app, keep the CLI running. Managed install does not file the request — open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link; the same URL is <strong>Send a reminder</strong> after you submit). After an admin approves, click <strong>Retry</strong> in the wizard.</p><p>Useful companions: <code>--name</code> / <code>--icon</code> / <code>--channel-posts</code> prefill the wizard. <code>--slack-team T0123ABCD</code> picks a workspace when several are connected. A second <code>slack create</code> for the same agent and env overwrites that Slack app. It keeps the Slack app id and replaces the manifest and tokens. <code>agent-sdk slack destroy</code> deletes the provisioned app. <code>agent-sdk slack icon &lt;source&gt;</code> updates the icon later.</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> on an agent and click <strong>Add Slack to this agent</strong>, or follow the URL <code>slack create</code> printed.</p><p>A first-run agent that has no hosted engine yet shows <strong>Not deployed yet</strong>. Local <code>agent-sdk serve</code> works from <code>.env.local</code>. The next <strong>Deploy</strong> injects the stored secrets; there is no Slack-only Redeploy.</p><p>If Slack needs admin approval, the wizard waits. Click <strong>Request approval</strong> to file the request in Slack (that same page later sends a reminder). After an admin approves, click <strong>Retry</strong>.</p><p>The app row&#39;s menu covers later care: rename, set an icon, rotate tokens, remove the app, or disconnect the workspace.</p><h3 id="wire-the-env-and-verify" tabindex="-1">Wire the env and verify <a class="header-anchor" href="#wire-the-env-and-verify" aria-label="Permalink to &quot;Wire the env and verify&quot;">​</a></h3><p><code>agent-sdk slack create</code> already wrote the tokens to <code>.env.local</code>, so after provisioning skip straight to <code>doctor</code>. <code>serve</code> / <code>dev</code> / <code>slack doctor</code> load that file (real environment variables always win).</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;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> MY_AGENT</span></span></code></pre></div><p>Proceed when <code>app_token</code>, <code>connections_open</code>, <code>bot_token</code>, and <code>auth_test</code> are all green. Then serve and smoke 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;">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>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># expect: [agent-sdk/slack] Socket Mode connected</span></span></code></pre></div><p>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 (<code>inbound kind=app_mention</code>, <code>session start</code>, <code>reply delivered via stream|postMessage</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 by default. Watching channels means dispatching on new posts without a mention. That&#39;s an explicit 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>
@@ -33,15 +32,11 @@ import{_ as a,c as e,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // same contract as onAppMention: return null to skip</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>Channel watching needs the <code>message.channels</code> / <code>message.groups</code> events on the Slack app (Socket Mode only — not available with <code>cursorAccount: true</code>). Generate manifests with <code>slack init --channel-posts</code>, or add the events and re-import. The bot must also be a member of each watched channel. Posts that mention the bot stay on the <code>app_mention</code> path, bot-authored posts never dispatch by default, and deleting a post inside the debounce window cancels its dispatch. Watched posts reuse the thread-scoped principal, so a later @mention continues the same session. Set <code>engagement.mentions</code> or <code>engagement.directMessages</code> to <code>false</code> to turn those surfaces off.</p><p>Set <code>includeBotPosts: true</code> when the posts worth watching come from bots: alert feeds, webhook integrations, or other agents posting notes. The watching app&#39;s own posts stay dropped either way, matched by the <code>bot_id</code> and bot user id from <code>auth.test</code>, so an agent can never dispatch on its own replies. The <a href="./../example-agents/oncall.html">alert investigator example</a> watches a bot-fed alerts channel this way.</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. It&#39;s the same host-prep pattern as <a href="./webhooks.html#prepare-on-the-host-then-hand-off">custom channels</a>. PR agents use it: extract a PR URL from the mention text and run the same host path as the HTTP channel.</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. Route that through 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;">});</span></span></code></pre></div><p>Channel watching needs the <code>message.channels</code> / <code>message.groups</code> events on the Slack app (Socket Mode only; not available with <code>cursorAccount: true</code>). Pass <code>--channel-posts</code> on <code>slack create</code>. The bot must also be a member of each watched channel.</p><p>Set <code>includeBotPosts: true</code> when the posts worth watching come from bots: alert feeds, webhook integrations, or other agents posting notes. The watching app&#39;s own posts stay dropped either way, matched by the <code>bot_id</code> and bot user id from <code>auth.test</code>, so an agent can never dispatch on its own replies. The <a href="./../example-agents/oncall.html">alert investigator example</a> watches a bot-fed alerts channel this way.</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. It&#39;s the same host-prep pattern as <a href="./webhooks.html#prepare-on-the-host-then-hand-off">custom channels</a>. PR agents use it: extract a PR URL from the mention text and run the same host path as the HTTP channel.</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. Route that through 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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// posts Block Kit Approve/Deny cards + routes clicks</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The Slack app manifest must have interactivity enabled. Regenerate with <code>buildSlackManifest({ interactivity: true })</code> (or edit and re-import) if your app predates it. Composing events by hand instead: spread <code>buildToolApprovalEvents({ credentials })</code> into <code>events</code> and set <code>interactivity: true</code> on the channel so Socket Mode routes the clicks.</p><p>Approval buttons need Socket Mode. <code>slackChannel({ cursorAccount: true })</code> rejects <code>toolApprovals</code> and <code>interactivity</code> at construction, since the Cursor Slack connection does not relay Block Kit clicks. Use a dedicated Slack app to run approvals for a cursor-account agent.</p><p>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 <code>execution: &quot;server&quot;</code> tools on the local runtime only, and parked calls do not survive a host restart. The full lifecycle is in <a href="./human-in-the-loop.html">Human-in-the-loop</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>One Slack app and token pair per agent. Never share a pair across agents in the same process. <code>envPrefix</code> keeps them apart (<code>WEATHER_AGENT_SLACK_*</code>, <code>TRIAGE_SLACK_*</code>, …), and agents without tokens mount with their Slack channel idle while everything else serves normally.</p><h2 id="keep-the-channel-healthy" tabindex="-1">Keep the channel healthy <a class="header-anchor" href="#keep-the-channel-healthy" aria-label="Permalink to &quot;Keep the channel healthy&quot;">​</a></h2><p>Two habits matter most.</p><ul><li>Don&#39;t <code>await</code> long work inside Slack dispatch handlers. The pack dispatches through <code>waitUntil</code> and streams as the turn progresses.</li><li>In <code>--dev</code> (loopback) or <code>--allow-anonymous</code> (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.</li></ul><h2 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h2><p>The <code>slack</code> subcommands cover setup end to end.</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;"> setup</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                     # guided checklist</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:#6A737D;--shiki-dark:#6A737D;">            # provision via Add to Slack (dev app)</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Approval cards need interactivity on the Slack app. Recreate with <code>slack create</code> if clicks do nothing. Composing events by hand: spread <code>buildToolApprovalEvents({ credentials })</code> into <code>events</code> and set <code>interactivity: true</code> on the channel so Socket Mode routes the clicks.</p><p>Approval buttons need Socket Mode. <code>slackChannel({ cursorAccount: true })</code> rejects <code>toolApprovals</code> and <code>interactivity</code> at construction, since the Cursor Slack connection does not relay Block Kit clicks. Use a dedicated Slack app to run approvals for a cursor-account agent.</p><p>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 <code>execution: &quot;server&quot;</code> tools on the local runtime only, and parked calls do not survive a host restart. The full lifecycle is in <a href="./human-in-the-loop.html">Human-in-the-loop</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>One Slack app and token pair per agent. Never share a pair across agents in the same process. <code>envPrefix</code> keeps them apart (<code>WEATHER_AGENT_SLACK_*</code>, <code>TRIAGE_SLACK_*</code>, …), and agents without tokens mount with their Slack channel idle while everything else serves normally.</p><h2 id="keep-the-channel-healthy" tabindex="-1">Keep the channel healthy <a class="header-anchor" href="#keep-the-channel-healthy" aria-label="Permalink to &quot;Keep the channel healthy&quot;">​</a></h2><p>Two habits matter most.</p><ul><li>Don&#39;t <code>await</code> long work inside Slack dispatch handlers. The pack dispatches through <code>waitUntil</code> and streams as the turn progresses.</li><li>In <code>--dev</code> (loopback) or <code>--allow-anonymous</code> (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.</li></ul><h2 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h2><p>The <code>slack</code> subcommands cover setup end to end.</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;"> setup</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">                     # two-product chooser</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:#6A737D;--shiki-dark:#6A737D;">            # dashboard wizard (dev app)</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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">     # prod app</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;"> destroy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # delete the provisioned app</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;"> icon</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./icon.png</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # set the provisioned app&#39;s icon</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;"> init</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>
-<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;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --no-prefix</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # shared SLACK_* vars</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;"> init</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;"> --channel-posts</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;"> manifest</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> both</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">       # regenerate manifests</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;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> MY_AGENT</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # token / connectivity checks</span></span></code></pre></div><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><p>Continue with these pages:</p><ul><li><a href="./human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle behind <code>toolApprovals</code></li><li><a href="./webhooks.html">Webhooks and custom channels</a>: the mechanism this pack is built on</li></ul>`,70)])])}const g=a(n,[["render",h]]);export{c as __pageData,g as default};
+<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;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> MY_AGENT</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # token / connectivity checks</span></span></code></pre></div><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><p>Continue with these pages:</p><ul><li><a href="./human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle behind <code>toolApprovals</code></li><li><a href="./webhooks.html">Webhooks and custom channels</a>: the mechanism this pack is built on</li></ul>`,61)])])}const g=e(n,[["render",h]]);export{k as __pageData,g as default};

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

@@ -0,0 +1 @@
+import{_ as e,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Slack","description":"Put the agent in Slack: Cursor-hosted connection or a dedicated Socket Mode app via the dashboard wizard, plus doctor, engagement rules, access policy, and approval buttons.","frontmatter":{"title":"Slack","description":"Put the agent in Slack: Cursor-hosted connection or a dedicated Socket Mode app via the dashboard wizard, plus doctor, engagement rules, access policy, and approval buttons."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function h(l,s,o,p,r,d){return i(),a("div",null,[...s[0]||(s[0]=[t("",61)])])}const g=e(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.BDmjPPAm.js → reference_cli.md.CGKfz_Yj.js}

@@ -57,17 +57,13 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> unset</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> NAME</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Pass names only. On a TTY, <code>secrets set</code> prompts for each value with hidden input (nothing echoes). When stdin is piped, provide one line per name. Values never print on stdout.</p><p>Do not put values on the command line. <code>NAME=VALUE</code> in argv shows up in shell history and in agent-captured terminals. The CLI refuses that form unless you pass <code>--from-argv</code> (still warns). Prefer a file redirect when a human is not at the prompt:</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;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> WEATHER_API_KEY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./weather-api-key.txt</span></span></code></pre></div><p>Secret names use <code>UPPER_SNAKE_CASE</code>, start with a letter, and contain at most 64 characters. Names beginning with <code>CURSOR_</code> are reserved. Values can contain at most 4096 bytes, and one deployment can hold 32 secrets.</p><p><code>secrets list</code> returns names and creation times, never values. Secret changes reach the engine on its next deploy. <code>secrets set</code> upserts the named secrets without deleting others.</p><p>JSON output is <code>{ secretNames }</code> for <code>set</code>, <code>{ secrets }</code> for <code>list</code>, and <code>{ removed }</code> for <code>unset</code>.</p><h2 id="slack" tabindex="-1">slack <a class="header-anchor" href="#slack" aria-label="Permalink to &quot;slack&quot;">​</a></h2><p>The <code>slack</code> pack provisions, generates, and checks Socket Mode channel setup.</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;"> setup</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:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prod]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                      [--slack-team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">T…</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</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:#24292E;--shiki-dark:#E1E4E8;">                      [--icon </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https-url-or-file</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--force]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                      [--icon </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https-url-or-file</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:#24292E;--shiki-dark:#E1E4E8;">                      [--prefix </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prefix</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --no-prefix] [--json]</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;"> destroy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prod] [--slack-team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">T…</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:#24292E;--shiki-dark:#E1E4E8;">                       [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</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;"> icon</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">https-url-or-fil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prod]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                    [--slack-team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">T…</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</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;"> init</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                    [--prefix </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prefix</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --no-prefix] [--channel-posts]</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;"> manifest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                        [--env dev</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prod</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">both] [--channel-posts] [--print]</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;"> doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prefix </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">prefi</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">x</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --no-prefix]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>slack setup</code> prints a guided checklist and doesn&#39;t change files.</p><p><code>slack create</code> provisions a dedicated Socket Mode app through Cursor&#39;s Add to Slack API instead of the manual manifest import. It requires a signed-in host (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>) and the provisioning feature to be enabled for the account. The command scaffolds the channel file when missing, opens the browser consent flow when the workspace isn&#39;t connected to Cursor yet, creates and installs the app, writes the bot and app-level tokens into <code>&lt;dir&gt;/.env.local</code>, and ends with a <code>doctor</code> pass. <code>--prod</code> provisions the production app; the default is the development app. When the install needs a Slack workspace admin&#39;s approval, the command prints the approval page and exits non-zero; re-run it after the approval to finish and mint the tokens. A re-run rebuilds the manifest from the command&#39;s flags and refuses to overwrite edits made by hand in Slack unless you pass <code>--force</code>.</p><p><code>slack destroy</code> deletes the provisioned app for the selected environment. Tokens already written to <code>.env.local</code> stay in place and stop working.</p><p><code>slack icon</code> sets the provisioned app&#39;s icon from an https image URL or a local png, jpg, or gif file of at most 512KB.</p><p><code>slack init</code> creates the channel file, development and production manifests, <code>env.example</code>, and setup status under the project. It refuses to overwrite a target file. If a collision occurs, it exits non-zero; files created earlier in the run remain. The token prefix defaults to the directory basename normalized to uppercase snake case. Explicit <code>--prefix</code> values use the same normalization when the Agent SDK builds token variable names. For example, <code>pr-approver</code> becomes <code>PR_APPROVER_SLACK_BOT_TOKEN</code>. <code>--no-prefix</code> uses shared <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. <code>--channel-posts</code> subscribes the manifests to channel-post events. The command always prints a JSON summary.</p><p><code>slack manifest</code> regenerates selected manifest files. <code>--env</code> defaults to <code>both</code>, and <code>--name</code> defaults to the directory name. <code>--print</code> writes the manifest JSON to stdout instead of changing files. With the default <code>--env both</code>, it prints development JSON, a <code>--- prod ---</code> separator, then production JSON.</p><p><code>slack doctor</code> checks both tokens, Socket Mode connectivity, and Slack&#39;s <code>auth.test</code>. It exits non-zero when any check fails.</p><p>See the <a href="./../guides/slack.html">Slack guide</a>.</p><h2 id="github" tabindex="-1">github <a class="header-anchor" href="#github" aria-label="Permalink to &quot;github&quot;">​</a></h2><p>The <code>github</code> pack discovers <code>githubChannel()</code> definitions and sends live or synthesized deliveries to them.</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--install] [--json]</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;"> doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--prefix </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">prefi</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">x</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --no-prefix]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p><code>slack setup</code> prints the two-product chooser and doesn&#39;t change files.</p><p><code>slack create</code> opens the signed-in Cursor dashboard wizard. Finish Slack consent and the bot name there. The CLI writes the token pair into <code>&lt;dir&gt;/.env.local</code> and runs <code>doctor</code>. It requires a signed-in host (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>). <code>--prod</code> provisions the production app; the default is the development app. <code>--name</code> / <code>--icon</code> / <code>--channel-posts</code> prefill the wizard. A second create for the same slug and env overwrites the live Slack app. If Slack needs a workspace admin&#39;s approval, the wizard waits; keep the CLI running, open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link), and click <strong>Retry</strong> after the admin approves. Token values never print.</p><p><code>slack destroy</code> deletes the provisioned app for the selected environment. Tokens already written to <code>.env.local</code> stay in place and stop working.</p><p><code>slack icon</code> sets the provisioned app&#39;s icon from an https image URL or a local png, jpg, or gif file of at most 512KB.</p><p><code>slack init</code> is removed. It exits non-zero and writes no files. Use <code>slack create</code>.</p><p><code>slack doctor</code> checks both tokens, Socket Mode connectivity, and Slack&#39;s <code>auth.test</code>. It exits non-zero when any check fails.</p><p>See the <a href="./../guides/slack.html">Slack guide</a>.</p><h2 id="github" tabindex="-1">github <a class="header-anchor" href="#github" aria-label="Permalink to &quot;github&quot;">​</a></h2><p>The <code>github</code> pack discovers <code>githubChannel()</code> definitions and sends live or synthesized deliveries to them.</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--install] [--json]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> events</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">hos</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> forward</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--channel </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--repo owner/repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --org </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">org</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--events a,b,c] [--url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
@@ -76,4 +72,4 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--events a,b,c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;*&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">action</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</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:#24292E;--shiki-dark:#E1E4E8;">    [--comment </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--context </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--channel </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</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:#24292E;--shiki-dark:#E1E4E8;">    [--host </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">host</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--port </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--secret </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</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:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><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="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,193)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</td></tr></tbody></table><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="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,192)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.BDmjPPAm.lean.js → reference_cli.md.CGKfz_Yj.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",193)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(d,s,l,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",192)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{troubleshooting.md.CkgwmVI0.js → troubleshooting.md.C6n3wCr6.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,ag as d}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,c,h,l){return a(),o("div",null,[...e[0]||(e[0]=[d('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with four checks, in order:</p><ol><li>Project discovery: <code>agent-sdk validate --dir .</code></li><li>Whether the serve process is running</li><li>What the playground or HTTP API shows</li><li>The session event stream (trace)</li></ol><p>Match your symptom below. Keep the commands as <code>agent-sdk</code>; see <a href="/docs/#run-the-cli">Run the CLI</a> if you still need an alias.</p><h2 id="what-if-serve-or-the-playground-looks-wrong" tabindex="-1">What if serve or the playground looks wrong? <a class="header-anchor" href="#what-if-serve-or-the-playground-looks-wrong" aria-label="Permalink to &quot;What if serve or the playground looks wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> won&#39;t start</td><td>Run <code>agent-sdk validate --dir .</code> and fix the reported errors.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>The UI needs a running <code>serve</code> process. Building the playground assets alone is not enough.</td></tr><tr><td>Edits to the playground don&#39;t show up</td><td>Use <code>serve --dev</code> and open the printed playground HMR URL (often port <code>5273</code>), not only the static <code>:3000</code> URL.</td></tr><tr><td>Sessions exist on disk but the playground list is empty</td><td>The list shows sessions for the authenticated caller. In <code>--dev</code> on loopback the list is wider. Otherwise open <code>/&lt;slug&gt;/playground?sessionId=ses_…</code> or inspect <code>sessions/</code> under your state root.</td></tr><tr><td>Port 3000 or 5273 is already in use</td><td>For the default serve port, the CLI tries the next free port and prints a notice. Pass <code>--port</code> to pick one, or <code>--port 0</code> for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port.</td></tr></tbody></table><h2 id="what-if-a-model-turn-goes-wrong" tabindex="-1">What if a model turn goes wrong? <a class="header-anchor" href="#what-if-a-model-turn-goes-wrong" aria-label="Permalink to &quot;What if a model turn goes wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Built-in file reads and greps fail; the turn retries for a long time</td><td>Run under Node 22.13+ (or <code>tsx</code>), never Bun. Look for <code>NGHTTP2_FRAME_SIZE_ERROR</code> in logs.</td></tr><tr><td>The turn fails immediately with an API-key error</td><td>Sign in with <code>agent-sdk login</code>, or set <code>CURSOR_API_KEY</code>. Discovery, <code>info</code>, <code>call</code>, and serve bring-up work without a key; model turns need one.</td></tr><tr><td>Replies quote rules or <code>AGENTS.md</code> from outside your agent project</td><td>The session workspace inherited parent-folder config. Point <code>defineAgent({ local: { cwd } })</code> outside that tree, or set <code>--state-root</code> to a clean directory (for example under <code>/tmp</code>).</td></tr><tr><td>Server tools, skills, or workspace seed files never appear</td><td>The agent runtime is <code>cloud</code>. Those features apply on the local runtime. <code>validate</code> warns when this combination is present.</td></tr><tr><td><code>validate</code> and <code>run</code> succeed, but typecheck fails in CI</td><td>The CLI runs TypeScript with type-stripping only. Keep tool <code>execute</code> return types as object literals or <code>type</code> aliases, not <code>interface</code> types.</td></tr><tr><td>Login works, but turns are rejected when using custom API hosts</td><td>Point login and model traffic at the same host (<code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>). A key from one host is rejected by the other.</td></tr></tbody></table><h2 id="what-if-the-http-api-returns-an-error" tabindex="-1">What if the HTTP API returns an error? <a class="header-anchor" href="#what-if-the-http-api-returns-an-error" aria-label="Permalink to &quot;What if the HTTP API returns an error?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>409</code> on a follow-up message</td><td>Refresh the <code>continuationToken</code> (it rotates on each accepted follow-up), wait if the session is busy, or confirm the session is a chat session (task and schedule sessions are not followable).</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>Wait for the model turn to finish, or omit <code>--session</code> for a one-off call.</td></tr><tr><td><code>403</code> on stream or follow-up</td><td>Use the same auth identity that created the session. Off localhost, pass <code>--bearer-token</code> and send it on every request.</td></tr><tr><td>Works on localhost; blocked through a tunnel or LAN</td><td>Default auth allows only direct loopback callers. Share the host with <code>--bearer-token &lt;secret&gt;</code> (or authored <code>bearerAuth</code>). Use <code>--allow-anonymous</code> only on a trusted private network.</td></tr><tr><td>A channel route fails to compile with a schema type error</td><td><code>GET</code> routes need a Zod <code>querySchema</code>. <code>POST</code> / <code>PUT</code> / <code>PATCH</code> need a Zod <code>bodySchema</code>. Use <code>z.object({})</code> or <code>z.unknown()</code> for open shapes.</td></tr></tbody></table><h2 id="what-if-github-webhooks-misbehave" tabindex="-1">What if GitHub webhooks misbehave? <a class="header-anchor" href="#what-if-github-webhooks-misbehave" aria-label="Permalink to &quot;What if GitHub webhooks misbehave?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery, but the hook was created</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command. The forwarder uses your <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …</code></td></tr><tr><td><code>Hook already exists</code> when starting a forwarder</td><td>GitHub allows one forwarder per repo. Run a single <code>github forward --dir &lt;parent&gt;</code> and stop stale forwarders.</td></tr><tr><td>Deliveries rejected outside <code>--dev</code></td><td>Set <code>GITHUB_WEBHOOK_SECRET</code> on the server and on the signer. Without a secret, the channel stays loopback-only.</td></tr><tr><td>You lack repo admin and can&#39;t forward</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>. It needs pull access only and posts signed test payloads.</td></tr></tbody></table><h2 id="what-if-slack-stays-quiet" tabindex="-1">What if Slack stays quiet? <a class="header-anchor" href="#what-if-slack-stays-quiet" aria-label="Permalink to &quot;What if Slack stays quiet?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs show <code>channel idle … missing credentials</code></td><td>Expected when tokens are missing. Run <code>agent-sdk slack create --dir &lt;agent&gt;</code> to provision the app and write the tokens, or set <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> per agent yourself, then run <code>agent-sdk slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td><code>slack create</code> reports the app needs admin approval</td><td>The workspace requires admin approval for new apps. A Slack workspace admin approves it at the printed link (in the dashboard: <strong>Approve in Slack</strong>), then re-run <code>agent-sdk slack create</code> (or <strong>Retry</strong> in the dashboard).</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Default engagement is mentions and DMs only. Enable <code>engagement.channelPosts</code> with an allowlist, and subscribe the app to <code>message.channels</code> / <code>message.groups</code>.</td></tr><tr><td>Approve / Deny buttons do nothing</td><td>Re-import a Slack app manifest with interactivity enabled. Channels that post approval cards need <code>toolApprovals: true</code> (and <code>interactivity: true</code> when you compose events by hand).</td></tr></tbody></table><h2 id="what-if-host-mcp-oauth-fails" tabindex="-1">What if host MCP OAuth fails? <a class="header-anchor" href="#what-if-host-mcp-oauth-fails" aria-label="Permalink to &quot;What if host MCP OAuth fails?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>The connection file needs <code>oauth: true</code>, or you passed the wrong connection name to <code>agent-sdk mcp oauth</code>.</td></tr><tr><td>Local auth works; hosted calls unauthorized</td><td>Run <code>agent-sdk mcp oauth &lt;name&gt; --store</code>, confirm names with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy.</td></tr><tr><td>Model asks for <code>mcp_auth</code> or IDE MCP for a privileged server</td><td>That connection is likely <code>hostOnly</code>. Call it from a host tool via <code>ctx.host.mcp</code>, and update instructions.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> and <a href="./../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-if-a-secret-showed-up-in-a-terminal-transcript" tabindex="-1">What if a secret showed up in a terminal transcript? <a class="header-anchor" href="#what-if-a-secret-showed-up-in-a-terminal-transcript" aria-label="Permalink to &quot;What if a secret showed up in a terminal transcript?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>secrets set … NAME=VALUE</code> in an agent-captured terminal or shell history</td><td>Rotate the secret at the provider. Set it again with names only: <code>agent-sdk secrets set &lt;slug&gt; NAME</code> (hidden prompt) or pipe/redirect the value. <code>NAME=VALUE</code> requires <code>--from-argv</code> and still leaks into argv.</td></tr><tr><td>Alias token printed during first deploy or <code>rotate-token</code></td><td>Treat it as exposed if the transcript left your machine. Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new token outside agent transcripts, and update callers.</td></tr><tr><td>Someone verified a secret with <code>echo</code> / <code>printenv</code></td><td>Rotate it. Confirm presence with <code>agent-sdk secrets list &lt;slug&gt;</code> (names only), then redeploy and test the feature.</td></tr></tbody></table><h2 id="what-if-schedules-reminders-or-approvals-stall" tabindex="-1">What if schedules, reminders, or approvals stall? <a class="header-anchor" href="#what-if-schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;What if schedules, reminders, or approvals stall?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Dev mode does not auto-fire. Trigger with <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code> or <code>POST /&lt;slug&gt;/v1/dev/reminders/&lt;id&gt;</code> (list reminders at <code>GET /v1/dev/reminders</code>).</td></tr><tr><td>A pending tool approval disappeared after restart</td><td>Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again.</td></tr><tr><td>A reminder is disarmed after restart (<code>handler_lost_on_restart</code>)</td><td>Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders.</td></tr></tbody></table><h2 id="how-do-i-read-a-session-trace" tabindex="-1">How do I read a session trace? <a class="header-anchor" href="#how-do-i-read-a-session-trace" aria-label="Permalink to &quot;How do I read a session trace?&quot;">​</a></h2><p>Look at <code>actions.requested</code> / <code>action.result</code> pairs for the tool trajectory. Count calls by tool name before blaming latency. Separate host-side work (channel <code>callTool</code>, preparation) from tools the model chose.</p><p><code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> means a follow-up or stop ended the turn on purpose.</p><p>If the model reads outside the session workspace, the prepared files don&#39;t match what the instructions expect. Fix the layout. See <a href="./hillclimbing.html">Hillclimbing</a>.</p><p><code>agent-sdk trajectory --events &lt;file&gt;</code> summarizes any saved NDJSON stream. The playground <strong>Open trace</strong> control does the same visually.</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="./concepts.html">Concepts</a>: the model behind these symptoms</li><li><a href="./hillclimbing.html">Hillclimbing</a>: when the agent runs but underperforms</li><li><a href="./deployment.html">Deployment</a>: auth and state on shared hosts</li></ul>',28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};
+import{_ as t,c as o,o as a,ag as d}from"./chunks/framework.CAZyNGu9.js";const p=JSON.parse('{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail.","frontmatter":{"title":"Fix common agent problems","description":"Match what you see to a cause, then read a session trace when you need more detail."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,c,h,l){return a(),o("div",null,[...e[0]||(e[0]=[d('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with four checks, in order:</p><ol><li>Project discovery: <code>agent-sdk validate --dir .</code></li><li>Whether the serve process is running</li><li>What the playground or HTTP API shows</li><li>The session event stream (trace)</li></ol><p>Match your symptom below. Keep the commands as <code>agent-sdk</code>; see <a href="/docs/#run-the-cli">Run the CLI</a> if you still need an alias.</p><h2 id="what-if-serve-or-the-playground-looks-wrong" tabindex="-1">What if serve or the playground looks wrong? <a class="header-anchor" href="#what-if-serve-or-the-playground-looks-wrong" aria-label="Permalink to &quot;What if serve or the playground looks wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> won&#39;t start</td><td>Run <code>agent-sdk validate --dir .</code> and fix the reported errors.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>The UI needs a running <code>serve</code> process. Building the playground assets alone is not enough.</td></tr><tr><td>Edits to the playground don&#39;t show up</td><td>Use <code>serve --dev</code> and open the printed playground HMR URL (often port <code>5273</code>), not only the static <code>:3000</code> URL.</td></tr><tr><td>Sessions exist on disk but the playground list is empty</td><td>The list shows sessions for the authenticated caller. In <code>--dev</code> on loopback the list is wider. Otherwise open <code>/&lt;slug&gt;/playground?sessionId=ses_…</code> or inspect <code>sessions/</code> under your state root.</td></tr><tr><td>Port 3000 or 5273 is already in use</td><td>For the default serve port, the CLI tries the next free port and prints a notice. Pass <code>--port</code> to pick one, or <code>--port 0</code> for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port.</td></tr></tbody></table><h2 id="what-if-a-model-turn-goes-wrong" tabindex="-1">What if a model turn goes wrong? <a class="header-anchor" href="#what-if-a-model-turn-goes-wrong" aria-label="Permalink to &quot;What if a model turn goes wrong?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Built-in file reads and greps fail; the turn retries for a long time</td><td>Run under Node 22.13+ (or <code>tsx</code>), never Bun. Look for <code>NGHTTP2_FRAME_SIZE_ERROR</code> in logs.</td></tr><tr><td>The turn fails immediately with an API-key error</td><td>Sign in with <code>agent-sdk login</code>, or set <code>CURSOR_API_KEY</code>. Discovery, <code>info</code>, <code>call</code>, and serve bring-up work without a key; model turns need one.</td></tr><tr><td>Replies quote rules or <code>AGENTS.md</code> from outside your agent project</td><td>The session workspace inherited parent-folder config. Point <code>defineAgent({ local: { cwd } })</code> outside that tree, or set <code>--state-root</code> to a clean directory (for example under <code>/tmp</code>).</td></tr><tr><td>Server tools, skills, or workspace seed files never appear</td><td>The agent runtime is <code>cloud</code>. Those features apply on the local runtime. <code>validate</code> warns when this combination is present.</td></tr><tr><td><code>validate</code> and <code>run</code> succeed, but typecheck fails in CI</td><td>The CLI runs TypeScript with type-stripping only. Keep tool <code>execute</code> return types as object literals or <code>type</code> aliases, not <code>interface</code> types.</td></tr><tr><td>Login works, but turns are rejected when using custom API hosts</td><td>Point login and model traffic at the same host (<code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>). A key from one host is rejected by the other.</td></tr></tbody></table><h2 id="what-if-the-http-api-returns-an-error" tabindex="-1">What if the HTTP API returns an error? <a class="header-anchor" href="#what-if-the-http-api-returns-an-error" aria-label="Permalink to &quot;What if the HTTP API returns an error?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>409</code> on a follow-up message</td><td>Refresh the <code>continuationToken</code> (it rotates on each accepted follow-up), wait if the session is busy, or confirm the session is a chat session (task and schedule sessions are not followable).</td></tr><tr><td><code>409 session_busy</code> on <code>call --session</code></td><td>Wait for the model turn to finish, or omit <code>--session</code> for a one-off call.</td></tr><tr><td><code>403</code> on stream or follow-up</td><td>Use the same auth identity that created the session. Off localhost, pass <code>--bearer-token</code> and send it on every request.</td></tr><tr><td>Works on localhost; blocked through a tunnel or LAN</td><td>Default auth allows only direct loopback callers. Share the host with <code>--bearer-token &lt;secret&gt;</code> (or authored <code>bearerAuth</code>). Use <code>--allow-anonymous</code> only on a trusted private network.</td></tr><tr><td>A channel route fails to compile with a schema type error</td><td><code>GET</code> routes need a Zod <code>querySchema</code>. <code>POST</code> / <code>PUT</code> / <code>PATCH</code> need a Zod <code>bodySchema</code>. Use <code>z.object({})</code> or <code>z.unknown()</code> for open shapes.</td></tr></tbody></table><h2 id="what-if-github-webhooks-misbehave" tabindex="-1">What if GitHub webhooks misbehave? <a class="header-anchor" href="#what-if-github-webhooks-misbehave" aria-label="Permalink to &quot;What if GitHub webhooks misbehave?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery, but the hook was created</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command. The forwarder uses your <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …</code></td></tr><tr><td><code>Hook already exists</code> when starting a forwarder</td><td>GitHub allows one forwarder per repo. Run a single <code>github forward --dir &lt;parent&gt;</code> and stop stale forwarders.</td></tr><tr><td>Deliveries rejected outside <code>--dev</code></td><td>Set <code>GITHUB_WEBHOOK_SECRET</code> on the server and on the signer. Without a secret, the channel stays loopback-only.</td></tr><tr><td>You lack repo admin and can&#39;t forward</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>. It needs pull access only and posts signed test payloads.</td></tr></tbody></table><h2 id="what-if-slack-stays-quiet" tabindex="-1">What if Slack stays quiet? <a class="header-anchor" href="#what-if-slack-stays-quiet" aria-label="Permalink to &quot;What if Slack stays quiet?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs show <code>channel idle … missing credentials</code></td><td>Expected when tokens are missing. Run <code>agent-sdk slack create --dir &lt;agent&gt;</code> to provision the app and write the tokens, or set <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> per agent yourself, then run <code>agent-sdk slack doctor --prefix &lt;PREFIX&gt;</code>.</td></tr><tr><td><code>slack create</code> reports the app needs admin approval</td><td>Open Slack&#39;s <strong>Request approval</strong> page (the CLI prints the link; the same URL is <strong>Send a reminder</strong> after you submit). Managed install does not file the request. Keep the CLI running, then click <strong>Retry</strong> in the dashboard after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Default engagement is mentions and DMs only. Enable <code>engagement.channelPosts</code> with an allowlist, and subscribe the app to <code>message.channels</code> / <code>message.groups</code>.</td></tr><tr><td>Approve / Deny buttons do nothing</td><td>Channels that post approval cards need <code>toolApprovals: true</code>. Recreate the app with <code>slack create</code> if interactivity is off.</td></tr></tbody></table><h2 id="what-if-host-mcp-oauth-fails" tabindex="-1">What if host MCP OAuth fails? <a class="header-anchor" href="#what-if-host-mcp-oauth-fails" aria-label="Permalink to &quot;What if host MCP OAuth fails?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>The connection file needs <code>oauth: true</code>, or you passed the wrong connection name to <code>agent-sdk mcp oauth</code>.</td></tr><tr><td>Local auth works; hosted calls unauthorized</td><td>Run <code>agent-sdk mcp oauth &lt;name&gt; --store</code>, confirm names with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy.</td></tr><tr><td>Model asks for <code>mcp_auth</code> or IDE MCP for a privileged server</td><td>That connection is likely <code>hostOnly</code>. Call it from a host tool via <code>ctx.host.mcp</code>, and update instructions.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> and <a href="./../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><h2 id="what-if-a-secret-showed-up-in-a-terminal-transcript" tabindex="-1">What if a secret showed up in a terminal transcript? <a class="header-anchor" href="#what-if-a-secret-showed-up-in-a-terminal-transcript" aria-label="Permalink to &quot;What if a secret showed up in a terminal transcript?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>secrets set … NAME=VALUE</code> in an agent-captured terminal or shell history</td><td>Rotate the secret at the provider. Set it again with names only: <code>agent-sdk secrets set &lt;slug&gt; NAME</code> (hidden prompt) or pipe/redirect the value. <code>NAME=VALUE</code> requires <code>--from-argv</code> and still leaks into argv.</td></tr><tr><td>Alias token printed during first deploy or <code>rotate-token</code></td><td>Treat it as exposed if the transcript left your machine. Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new token outside agent transcripts, and update callers.</td></tr><tr><td>Someone verified a secret with <code>echo</code> / <code>printenv</code></td><td>Rotate it. Confirm presence with <code>agent-sdk secrets list &lt;slug&gt;</code> (names only), then redeploy and test the feature.</td></tr></tbody></table><h2 id="what-if-schedules-reminders-or-approvals-stall" tabindex="-1">What if schedules, reminders, or approvals stall? <a class="header-anchor" href="#what-if-schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;What if schedules, reminders, or approvals stall?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Dev mode does not auto-fire. Trigger with <code>POST /&lt;slug&gt;/v1/dev/schedules/&lt;id&gt;</code> or <code>POST /&lt;slug&gt;/v1/dev/reminders/&lt;id&gt;</code> (list reminders at <code>GET /v1/dev/reminders</code>).</td></tr><tr><td>A pending tool approval disappeared after restart</td><td>Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again.</td></tr><tr><td>A reminder is disarmed after restart (<code>handler_lost_on_restart</code>)</td><td>Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders.</td></tr></tbody></table><h2 id="how-do-i-read-a-session-trace" tabindex="-1">How do I read a session trace? <a class="header-anchor" href="#how-do-i-read-a-session-trace" aria-label="Permalink to &quot;How do I read a session trace?&quot;">​</a></h2><p>Look at <code>actions.requested</code> / <code>action.result</code> pairs for the tool trajectory. Count calls by tool name before blaming latency. Separate host-side work (channel <code>callTool</code>, preparation) from tools the model chose.</p><p><code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code> means a follow-up or stop ended the turn on purpose.</p><p>If the model reads outside the session workspace, the prepared files don&#39;t match what the instructions expect. Fix the layout. See <a href="./hillclimbing.html">Hillclimbing</a>.</p><p><code>agent-sdk trajectory --events &lt;file&gt;</code> summarizes any saved NDJSON stream. The playground <strong>Open trace</strong> control does the same visually.</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="./concepts.html">Concepts</a>: the model behind these symptoms</li><li><a href="./hillclimbing.html">Hillclimbing</a>: when the agent runs but underperforms</li><li><a href="./deployment.html">Deployment</a>: auth and state on shared hosts</li></ul>',28)])])}const m=t(r,[["render",s]]);export{p as __pageData,m as default};

package/dist/docs/building-with-agents.html

@@ -9,9 +9,9 @@
     <link rel="preload stylesheet" href="/docs/assets/style.CK3hwt6q.css" as="style">
     <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
     
-    <script type="module" src="/docs/assets/app.BpWAgjaR.js"></script>
+    <script type="module" src="/docs/assets/app.Cbeq6FOy.js"></script>
     <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
-    <link rel="modulepreload" href="/docs/assets/chunks/theme.B5IvUxOB.js">
+    <link rel="modulepreload" href="/docs/assets/chunks/theme.BLNMeCRL.js">
     <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
     <link rel="modulepreload" href="/docs/assets/building-with-agents.md.PeZaZA1P.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
@@ -31,7 +31,7 @@
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</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;"> --list</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</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;"> --json</span></span></code></pre></div><p><code>serve</code> boots without an API key, which is enough to check channel mounts and the playground shell. Model turns need a credential. When the environment lacks one, finish every key-free check, then hand the <code>run</code> and <code>eval</code> commands to the operator.</p><p>Test server tools with <code>call</code> before tuning the prompt. It runs a tool in-process with schema validation and no model turn. If the tool returns the wrong data, a prompt change won&#39;t fix it.</p><p><code>validate</code> and <code>run</code> don&#39;t type-check the project because tsx strips types. Run the project&#39;s TypeScript check before shipping. Tool results must also be JSON-shaped. Use object literals or <code>type</code> aliases for <code>execute</code> return types instead of <code>interface</code> types.</p><h2 id="how-do-i-improve-the-agent-after-its-first-run" tabindex="-1">How do I improve the agent after its first run? <a class="header-anchor" href="#how-do-i-improve-the-agent-after-its-first-run" aria-label="Permalink to &quot;How do I improve the agent after its first run?&quot;">​</a></h2><p>Scaffolding proves the agent runs. It says nothing about quality. Once a smoke turn passes, give the hillclimb skill:</p><ol><li><strong>Fixtures</strong>: one to three fixed inputs, such as a PR URL, a canonical question, or a saved webhook payload</li><li><strong>Success criteria</strong>: correct tool choice, fewer tool calls, lower wall time, or better output</li><li><strong>The freeze line</strong>: the API contract, output shape, and existing evals that must stay unchanged</li></ol><p>Have the coding agent read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. It measures the current run, proposes one change, remeasures the same fixtures, and adds an eval for each kept improvement.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Create your first agent</a></li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/cli.html">CLI reference</a></li></ul></div></div></main><footer class="VPDocFooter" data-v-d5d7ccd1 data-v-a5908b0f><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-a5908b0f><span class="visually-hidden" id="doc-footer-aria-label" data-v-a5908b0f>Pager</span><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link prev" href="/docs/templates/triage.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Previous page</span><span class="title" data-v-a5908b0f>Triage agent</span><!--]--></a></div><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link next" href="/docs/evals.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Next page</span><span class="title" data-v-a5908b0f>Evals</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"Cdp4rTE4\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"l7JTmm8X\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"ZE0n6ZFN\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"B8QKtIpw\",\"guides_human-in-the-loop.md\":\"BWvT7UqY\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"zriQpU_9\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"COeoSkcF\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"BDmjPPAm\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"kJfJAP2m\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"D8NQ389l\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"CkgwmVI0\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_github.md\":\"B8QKtIpw\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"D2nTRu9M\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"COeoSkcF\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"CGKfz_Yj\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"kJfJAP2m\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"D8NQ389l\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"C6n3wCr6\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>