@cursor/july 0.1.93 → 0.1.95

package/dist/docs/assets/example-agents_knowledge-base.md.CrA85ig-.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Build a team knowledge base through conversation","description":"Teach an agent about people, systems, decisions, and preferences; store that knowledge as markdown and retrieve it in fresh sessions.","frontmatter":{"title":"Build a team knowledge base through conversation","description":"Teach an agent about people, systems, decisions, and preferences; store that knowledge as markdown and retrieve it in fresh sessions."},"headers":[],"relativePath":"example-agents/knowledge-base.md","filePath":"example-agents/knowledge-base.md"}'),n={name:"example-agents/knowledge-base.md"};function l(o,e,d,r,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i("",43)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_oncall.md.DK4XkYTd.js

@@ -1,10 +0,0 @@
-import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Investigate every alert in its own Slack thread","description":"Watch a bot-fed alerts channel, react when the agent locks in, coalesce thread chatter behind a quiet window, and let the agent schedule its own re-checks.","frontmatter":{"title":"Investigate every alert in its own Slack thread","description":"Watch a bot-fed alerts channel, react when the agent locks in, coalesce thread chatter behind a quiet window, and let the agent schedule its own re-checks."},"headers":[],"relativePath":"example-agents/oncall.md","filePath":"example-agents/oncall.md"}'),n={name:"example-agents/oncall.md"};function l(o,e,h,r,d,c){return s(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="investigate-every-alert-in-its-own-slack-thread" tabindex="-1">Investigate every alert in its own Slack thread <a class="header-anchor" href="#investigate-every-alert-in-its-own-slack-thread" aria-label="Permalink to &quot;Investigate every alert in its own Slack thread&quot;">​</a></h1><p>This agent is an on-call teammate. Alert feeds post into an alerts channel as bots. Each new alert dispatches an investigation session pinned to that post&#39;s thread: the agent reacts 👀 the moment it locks in, investigates immediately, and posts brief findings backed by evidence it observed. Replies in the thread reach it only after the thread has been quiet for about a minute, and reminder tools let it wake itself later to re-check a baseline or confirm an alert cleared.</p><p>Use this example when alerts land in Slack and you want one thread-scoped investigation per alert, with an agent that paces its own engagement instead of answering every message.</p><p><a href="./../../examples/oncall/">Browse the current alert-investigator source.</a></p><h2 id="follow-an-alert" tabindex="-1">Follow an alert <a class="header-anchor" href="#follow-an-alert" aria-label="Permalink to &quot;Follow an alert&quot;">​</a></h2><ol><li>An alert feed (Alertmanager, PagerDuty, Datadog) posts a new top-level message in the watched alerts channel.</li><li>The channel watch accepts it. <code>includeBotPosts</code> lets bot authors through; the agent&#39;s own posts always stay dropped.</li><li>The handler reacts 👀 on the alert post and sets &quot;Investigating…&quot; typing. The reaction is the lock-in signal: this alert has an owner.</li><li>The Agent SDK creates a session keyed to the alert&#39;s thread and dispatches immediately. New alerts get no debounce.</li><li>The agent reads the alert, gathers evidence, and posts findings to the thread once it has a hypothesis.</li><li>People discuss in the thread. Replies buffer per thread and dispatch as one coalesced follow-up after roughly a minute of quiet.</li><li>The agent arms reminders for anything that needs time and posts interim updates when new evidence changes the picture.</li></ol><p>Mentions and DMs skip the watch entirely and behave like ordinary chat.</p><h2 id="map-the-files" tabindex="-1">Map the files <a class="header-anchor" href="#map-the-files" aria-label="Permalink to &quot;Map the files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/oncall/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Names the agent and keeps harness workspaces outside any monorepo checkout.</td></tr><tr><td><a href="./../../examples/oncall/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Engagement rules, the investigation loop, and the message discipline.</td></tr><tr><td><a href="../../examples/oncall/agent/channels/slack-app.ts"><code>agent/channels/slack-app.ts</code></a></td><td>Dedicated Socket Mode app: watch configuration and handler wiring.</td></tr><tr><td><a href="../../examples/oncall/agent/lib/alert-watch.ts"><code>agent/lib/alert-watch.ts</code></a></td><td>The engagement policy: lock in on new alerts, coalesce replies.</td></tr><tr><td><a href="../../examples/oncall/agent/lib/thread-debounce.ts"><code>agent/lib/thread-debounce.ts</code></a></td><td>Per-thread quiet window.</td></tr><tr><td><a href="../../examples/oncall/agent/lib/alerts.ts"><code>agent/lib/alerts.ts</code></a></td><td>Dispatch classification, prompt building, and thread addressing.</td></tr><tr><td><a href="../../examples/oncall/agent/lib/slack-api.ts"><code>agent/lib/slack-api.ts</code></a></td><td>Reactions and thread posts on this agent&#39;s own token pair.</td></tr><tr><td><a href="../../examples/oncall/agent/tools/reminders_create.ts"><code>agent/tools/reminders_create.ts</code></a></td><td>Self-scheduled wakes bound to the thread (plus <code>reminders_list</code> and <code>reminders_cancel</code>).</td></tr><tr><td><a href="../../examples/oncall/agent/tools/post_thread_update.ts"><code>agent/tools/post_thread_update.ts</code></a></td><td>Interim updates to the thread mid-turn.</td></tr><tr><td><a href="../../examples/oncall/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persists sessions and events with <code>cursorHostedStorage</code>.</td></tr><tr><td><a href="../../examples/oncall/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/oncall/evals/smoke.eval.ts"><code>evals/smoke.eval.ts</code></a></td><td>Checks identity and the reminder-tool route.</td></tr></tbody></table><h2 id="let-bot-posts-through-the-watch" tabindex="-1">Let bot posts through the watch <a class="header-anchor" href="#let-bot-posts-through-the-watch" aria-label="Permalink to &quot;Let bot posts through the watch&quot;">​</a></h2><p>Channel watching drops bot-authored posts by default so two agents can never feed each other. Alert channels invert the assumption: the posts worth watching come from bots. <code>channelPosts.includeBotPosts</code> opts in per channel:</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:#6F42C1;--shiki-dark:#B392F0;">engagement</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  channelPosts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    allow</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;#alerts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    posts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;all&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    includeBotPosts</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Loop safety survives the opt-in. The pack matches the watching app&#39;s own posts by the <code>bot_id</code> and bot user id from <code>auth.test</code> and drops them, so the agent&#39;s findings never re-dispatch it. Posts that mention the bot stay on the mention path.</p><p><code>posts: &quot;all&quot;</code> also delivers thread replies. The handler, not the pack, decides their pace.</p><h2 id="pace-the-engagement" tabindex="-1">Pace the engagement <a class="header-anchor" href="#pace-the-engagement" aria-label="Permalink to &quot;Pace the engagement&quot;">​</a></h2><p>The example runs two rhythms:</p><ul><li>A new alert dispatches immediately.</li><li>Thread replies produce one engagement per lull.</li></ul><p>The pack&#39;s <code>debounceMs</code> is per message; it exists to let edits settle. This agent needs a per-thread window instead, so the handler owns it (<a href="../../examples/oncall/agent/lib/thread-debounce.ts"><code>lib/thread-debounce.ts</code></a>). Every reply restarts a 60-second timer keyed by thread. Superseded waiters resolve <code>null</code> and the handler returns <code>null</code> for them. When the thread goes quiet, the newest waiter receives the whole batch and dispatches one follow-up that lists every message with mentionable attribution.</p><p>Two details make the window matter. A follow-up that arrives while a turn runs preempts that turn (latest message wins), so engaging per message would keep cancelling the investigation. And @mentions bypass the window through Slack&#39;s mention path, so a person who needs the agent now still gets it now.</p><h2 id="schedule-your-own-re-checks" tabindex="-1">Schedule your own re-checks <a class="header-anchor" href="#schedule-your-own-re-checks" aria-label="Permalink to &quot;Schedule your own re-checks&quot;">​</a></h2><p>Investigations rarely finish in one pass. A baseline comparison needs 20 minutes of data. An alert that cleared may re-fire. The example hands the model three tools over <code>host.reminders</code>:</p><ul><li><code>reminders_create</code> arms a one-shot (<code>delay: &quot;20m&quot;</code>) or recurring (<code>every: &quot;30m&quot;</code> with a plain-language stop condition) wake bound to the thread&#39;s conversation.</li><li><code>reminders_list</code> shows the thread&#39;s standing watches.</li><li><code>reminders_cancel</code> disarms one, and refuses ids that belong to another thread&#39;s conversation.</li></ul><p>When a reminder fires, its prompt returns to the same session as a follow-up turn, and the reply lands in the alert thread. The instructions keep wake prompts generic (re-read live state instead of replaying stale numbers) and wake replies to one line, for example &quot;re-checked p99 on api-gateway: 120ms, back at baseline, cancelling the watch.&quot;</p><p>Keep these tool filenames if you copy the design: the framework&#39;s reminder fire prompt tells the model to call <code>reminders_cancel</code> by name when a stop condition is set.</p><h2 id="alert-people-mid-investigation" tabindex="-1">Alert people mid-investigation <a class="header-anchor" href="#alert-people-mid-investigation" aria-label="Permalink to &quot;Alert people mid-investigation&quot;">​</a></h2><p>The final reply of each turn posts to the thread on its own. <code>post_thread_update</code> covers evidence that shouldn&#39;t wait for the turn to finish: it posts a one-or-two-sentence update through the agent&#39;s token, with <code>&lt;@USERID&gt;</code> mentions for the people who need to act. The instructions restrict it to changes in hypothesis, severity, or blast radius. Progress narration doesn&#39;t qualify.</p><h2 id="connect-the-slack-app" tabindex="-1">Connect the Slack app <a class="header-anchor" href="#connect-the-slack-app" aria-label="Permalink to &quot;Connect the Slack app&quot;">​</a></h2><p>Channel watching is Socket Mode only, so this example uses a dedicated app:</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;"> examples/oncall</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --name</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Oncall&quot;</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;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ONCALL</span></span></code></pre></div><p><code>--channel-posts</code> prefills channel-watch events (<code>message.channels</code> / <code>message.groups</code>). Invite the bot to each watched channel after the wizard finishes.</p><p><code>ONCALL_ALERTS_CHANNELS</code> sets the watch list as comma-separated ids or <code>#names</code>. It defaults to <code>#alerts</code>.</p><p>Wire observability MCP servers under <code>agent/mcp-connections/</code> so evidence gathering reaches your logs, metrics, and dashboards. The example ships none; without them the agent works from the alert text, its links, and the thread.</p><h2 id="validate-and-start-the-server" tabindex="-1">Validate and start the server <a class="header-anchor" href="#validate-and-start-the-server" aria-label="Permalink to &quot;Validate and start the server&quot;">​</a></h2><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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/oncall</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/oncall</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/oncall</span></span></code></pre></div><p>The info output lists four server tools and the watched channel on the <code>slack-app</code> channel. Missing tokens leave that channel idle without stopping the server.</p><p>In dev mode, reminder timers don&#39;t auto-fire. List and fire them by hand through the dev routes described in <a href="./../reference/schedules.html#dispatch-and-dev-mode">Schedules and reminders</a>.</p><h2 id="test-the-policy-without-slack" tabindex="-1">Test the policy without Slack <a class="header-anchor" href="#test-the-policy-without-slack" aria-label="Permalink to &quot;Test the policy without Slack&quot;">​</a></h2><p>The engagement policy is plain code with unit tests:</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;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vitest</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/oncall</span></span></code></pre></div><p>The integration test drives a synthetic Events API delivery through the real parse, watch, and dispatch plumbing. It asserts a bot alert dispatches pinned to its thread after the lock-in reaction, the agent&#39;s own posts never loop, and replies coalesce behind the quiet window.</p><p>The smoke eval spends a model turn:</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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/oncall</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>It checks identity and the reminder-tool route lexically. It doesn&#39;t prove Slack delivery or reaction behavior; the unit tests cover the dispatch side, and a live check needs the dedicated app connected.</p><h2 id="build-an-alert-investigator" tabindex="-1">Build an alert investigator <a class="header-anchor" href="#build-an-alert-investigator" aria-label="Permalink to &quot;Build an alert investigator&quot;">​</a></h2><p>Use this structure when a bot feed should drive thread-scoped work:</p><ol><li>Watch the feed channel with <code>includeBotPosts: true</code> and a narrow allowlist.</li><li>Acknowledge on the triggering post before dispatching, so people see ownership without opening the thread.</li><li>Dispatch new items immediately; coalesce thread chatter behind a per-thread quiet window.</li><li>Give the agent reminder tools for anything that needs time, and make cancel discipline part of the instructions.</li><li>Keep every posted message brief and tied to evidence the agent saw.</li></ol><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/schedules.html">Schedules and reminders</a></li><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./benny.html">Playbook router</a> for the human-post variant of channel watching</li></ul>`,48)])])}const g=t(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_oncall.md.DK4XkYTd.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Investigate every alert in its own Slack thread","description":"Watch a bot-fed alerts channel, react when the agent locks in, coalesce thread chatter behind a quiet window, and let the agent schedule its own re-checks.","frontmatter":{"title":"Investigate every alert in its own Slack thread","description":"Watch a bot-fed alerts channel, react when the agent locks in, coalesce thread chatter behind a quiet window, and let the agent schedule its own re-checks."},"headers":[],"relativePath":"example-agents/oncall.md","filePath":"example-agents/oncall.md"}'),n={name:"example-agents/oncall.md"};function l(o,e,h,r,d,c){return s(),a("div",null,[...e[0]||(e[0]=[i("",48)])])}const g=t(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_security-reviewer.md.74pPpWYj.js

@@ -1,19 +0,0 @@
-import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Run staged security reviews from GitHub events","description":"Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics.","frontmatter":{"title":"Run staged security reviews from GitHub events","description":"Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics."},"headers":[],"relativePath":"example-agents/security-reviewer.md","filePath":"example-agents/security-reviewer.md"}'),r={name:"example-agents/security-reviewer.md"};function n(l,e,o,h,d,p){return a(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="run-staged-security-reviews-from-github-events" tabindex="-1">Run staged security reviews from GitHub events <a class="header-anchor" href="#run-staged-security-reviews-from-github-events" aria-label="Permalink to &quot;Run staged security reviews from GitHub events&quot;">​</a></h1><p>Security Reviewer turns a pull request into a staged host-side review. One tool prepares the diff and selects modules. A second fans out specialized reviewers and triages candidates as they arrive. A third deduplicates the confirmed findings, writes artifacts, and may publish a GitHub review.</p><p>Use this example when the workflow needs several model workers, but the host must own orchestration, progress, artifacts, and the final write.</p><p>Source lives under <a href="./../../../../factory/security-reviewer/"><code>factory/security-reviewer/</code></a> (factory agent, not under <code>examples/</code>).</p><p>Want one model turn and one comment? Scaffold the <a href="./../templates/security-reviewer.html">security-reviewer template</a>.</p><p><a href="./../../../../factory/security-reviewer/">Browse the Security Reviewer source.</a></p><h2 id="run-a-three-stage-host-pipeline" tabindex="-1">Run a three-stage host pipeline <a class="header-anchor" href="#run-a-three-stage-host-pipeline" aria-label="Permalink to &quot;Run a three-stage host pipeline&quot;">​</a></h2><p>Security Reviewer is a pipeline, not one long agent turn:</p><table tabindex="0"><thead><tr><th>Stage</th><th>Tool</th><th>Result</th></tr></thead><tbody><tr><td>Prepare</td><td><code>prepare_review</code></td><td>Fetch metadata and diff, create a <code>runId</code>, and select security modules.</td></tr><tr><td>Review and triage</td><td><code>run_reviewers</code></td><td>Run module reviewers in parallel and start triage as each candidate arrives.</td></tr><tr><td>Finalize</td><td><code>finalize_review</code></td><td>Apply thresholds, deduplicate findings, write artifacts, and optionally post a review.</td></tr></tbody></table><p><code>run_triage</code> remains available as a compatibility stage. In the normal flow, triage has already completed inside <code>run_reviewers</code>, so it reports existing results. If candidates exist without triage output, it starts triage workers and writes their state.</p><p>The configured root agent chooses and sequences tools in chat. The review workers use a model selected by the host pipeline. They are created programmatically with the agent SDK, not discovered from <code>agent/subagents/</code>.</p><h2 id="follow-a-github-review" tabindex="-1">Follow a GitHub review <a class="header-anchor" href="#follow-a-github-review" aria-label="Permalink to &quot;Follow a GitHub review&quot;">​</a></h2><ol><li>A pull request event starts a review and opens a playground session.</li><li>The playground shows reviewer and triage progress.</li><li>Confirmed findings appear in the PR review.</li><li>A GitHub Check reports completion or a processing failure.</li></ol><h2 id="map-the-framework-features" tabindex="-1">Map the framework features <a class="header-anchor" href="#map-the-framework-features" aria-label="Permalink to &quot;Map the framework features&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Capability</th><th>Source</th><th>Role</th></tr></thead><tbody><tr><td>Root agent</td><td><a href="../../../../factory/security-reviewer/agent/agent.ts"><code>agent/agent.ts</code></a>, <a href="./../../../../factory/security-reviewer/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Configure local chat and explain the three-stage contract.</td></tr><tr><td>Server tools</td><td><a href="./../../../../factory/security-reviewer/agent/tools/"><code>agent/tools/</code></a></td><td>Expose each review stage to chat and host orchestration.</td></tr><tr><td>GitHub channel</td><td><a href="../../../../factory/security-reviewer/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Filter wakes, run background tasks, and publish status.</td></tr><tr><td>Progress channel</td><td><a href="../../../../factory/security-reviewer/agent/channels/asr-progress.ts"><code>agent/channels/asr-progress.ts</code></a></td><td>Serve live reviewer and triage state by <code>runId</code>.</td></tr><tr><td>Playground renderer</td><td><a href="./../../../../factory/security-reviewer/agent/playground/tools/run_reviewers.tsx.html"><code>agent/playground/tools/run_reviewers.tsx</code></a></td><td>Replace the generic tool chip with live module rows.</td></tr><tr><td>SDK review pipeline</td><td><a href="../../../../factory/security-reviewer/agent/lib/review-stages.ts"><code>review-stages.ts</code></a>, <a href="../../../../packages/security-review-lib/src/index.ts"><code>@anysphere/security-review-lib</code></a></td><td>Select modules, call model workers, triage, deduplicate, and write artifacts.</td></tr><tr><td>Storage</td><td><a href="../../../../factory/security-reviewer/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persist framework sessions with <code>cursorHostedStorage</code> (lazy restore).</td></tr><tr><td>A/B</td><td><a href="../../../../factory/security-reviewer/agent/ab.ts"><code>agent/ab.ts</code></a></td><td>Compare all-severity versus high-only GitHub comments.</td></tr><tr><td>Eval</td><td><a href="./../../../../factory/security-reviewer/evals/"><code>evals/</code></a></td><td>Check stage-tool presence against a pinned sample.</td></tr></tbody></table><p>There is no Slack channel, authored skill, discovered subagent, MCP connection, schedule, reminder, hook, tool approval, or cloud runtime.</p><h2 id="prepare-the-host" tabindex="-1">Prepare the host <a class="header-anchor" href="#prepare-the-host" aria-label="Permalink to &quot;Prepare the host&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential for the root turn and review workers.</li><li>GitHub read access for preparation.</li><li>GitHub write access for webhook-driven reviews and Checks.</li></ul><p>The pipeline exposes settings for:</p><ul><li>the worker model,</li><li>reviewer and triage parallelism,</li><li>reviewer, triage, duplicate-gate, and final-dedupe timeouts, and</li><li>prior-comment loading.</li></ul><p>The active names live beside the orchestration in <a href="../../../../factory/security-reviewer/agent/lib/review-stages.ts"><code>review-stages.ts</code></a>.</p><h2 id="validate-the-discovered-agent" tabindex="-1">Validate the discovered agent <a class="header-anchor" href="#validate-the-discovered-agent" aria-label="Permalink to &quot;Validate the discovered agent&quot;">​</a></h2><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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p><code>validate</code> should pass. <code>info</code> and <code>eval --list</code> should match the capabilities mapped above.</p><h2 id="know-the-chat-path-s-write-boundary" tabindex="-1">Know the chat path&#39;s write boundary <a class="header-anchor" href="#know-the-chat-path-s-write-boundary" aria-label="Permalink to &quot;Know the chat path&#39;s write boundary&quot;">​</a></h2><p>In chat, the root instructions ask the model to use this order:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>prepare_review -&gt; run_reviewers -&gt; finalize_review</span></span></code></pre></div><p>They also ask the model to set <code>postComment: true</code> only on request. This is prompt policy, not a deterministic safety gate. The model chooses tool arguments, and <code>finalize_review</code> has no human approval. Use the direct stage calls below when a no-post proof must be enforced.</p><h2 id="call-stages-directly-without-publishing" tabindex="-1">Call stages directly without publishing <a class="header-anchor" href="#call-stages-directly-without-publishing" aria-label="Permalink to &quot;Call stages directly without publishing&quot;">​</a></h2><p>Call each stage and pass <code>postComment: false</code> yourself:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> prepare_review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/owner/repo/pull/123&quot;}&#39;</span></span>
-<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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run_reviewers</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;runId&quot;:&quot;&lt;run-id&gt;&quot;}&#39;</span></span>
-<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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> finalize_review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;runId&quot;:&quot;&lt;run-id&gt;&quot;,&quot;postComment&quot;:false}&#39;</span></span></code></pre></div><p>Review state lives under the project&#39;s run-artifact directory, so later stages can open the prepared <code>runId</code>.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p><code>finalize_review</code> with <code>postComment: true</code> writes to GitHub. The webhook path always requests that write. Chat instructions alone don&#39;t prevent it.</p></div><h2 id="watch-parallel-work-in-the-playground" tabindex="-1">Watch parallel work in the playground <a class="header-anchor" href="#watch-parallel-work-in-the-playground" aria-label="Permalink to &quot;Watch parallel work in the playground&quot;">​</a></h2><p>Run the dev server:</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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span></span></code></pre></div><p>Open the printed playground and start a review. The custom <code>run_reviewers</code> renderer polls the progress channel&#39;s <code>GET /:runId</code> route.</p><p>It refreshes every 500 ms while the stage runs. Each row shows a reviewer module&#39;s state, candidates, reviewed areas, and failure. A second section shows triage jobs and confirmed or rejected counts.</p><p>This is an authored playground extension. The Agent SDK discovers it by the tool name, so the generic <code>run_reviewers</code> chip becomes a domain-specific view without changing the framework playground.</p><h2 id="fan-out-reviewers-while-triage-starts" tabindex="-1">Fan out reviewers while triage starts <a class="header-anchor" href="#fan-out-reviewers-while-triage-starts" aria-label="Permalink to &quot;Fan out reviewers while triage starts&quot;">​</a></h2><p>Module selection uses repository and path rules. The current module set covers:</p><ul><li>agent tooling trust boundaries,</li><li>privileged service RPCs,</li><li>product-specific security risks,</li><li>dependency and supply-chain changes,</li><li>deployment and infrastructure code,</li><li>filesystem and workspace boundaries,</li><li>privacy, and</li><li>general security review.</li></ul><p>Selected modules may run more than once. Candidates pass through a duplicate gate, then bounded triage. Reviewer or triage failures can produce partial results. A final dedupe failure stops finalization.</p><p>The pipeline writes JSONL journals as work completes. Final artifacts include the review bundle, patch, reviewer outputs, candidates, triage decisions, findings, accounting, and audit events.</p><h2 id="separate-session-storage-from-review-artifacts" tabindex="-1">Separate session storage from review artifacts <a class="header-anchor" href="#separate-session-storage-from-review-artifacts" aria-label="Permalink to &quot;Separate session storage from review artifacts&quot;">​</a></h2><p><code>cursorHostedStorage</code> keeps Agent SDK session and event records on Cursor-managed hosting. Security Reviewer sets <code>restore: &quot;off&quot;</code> so startup doesn&#39;t load old review sessions in bulk. A continuation lookup can still fetch a needed session. See <a href="./../storage.html">Storage</a>.</p><p>The staged review files are separate from session storage. Session-store durability doesn&#39;t preserve those files. All stages for one <code>runId</code> must see the same filesystem.</p><p>This split is useful when conversation history needs shared durability but large review artifacts belong on attached storage or an object store.</p><h2 id="compare-live-comment-variants" tabindex="-1">Compare live comment variants <a class="header-anchor" href="#compare-live-comment-variants" aria-label="Permalink to &quot;Compare live comment variants&quot;">​</a></h2><p>The comment-severity experiment uses sticky session assignment with a 5% holdout:</p><ul><li><code>control</code> posts every finding.</li><li><code>treatment</code> posts only high and critical findings.</li></ul><p>Finalization enforces the comment filter. The treatment also adds an instruction overlay asking chat and playground summaries to lead with high and critical findings. Full artifacts, <code>finalResponse</code>, and finding counts still include every finding. Stage-tool counters appear in the playground A/B view. Local sample and snapshot files persist under the project state directory.</p><p>When a treatment session has only low or medium findings, the filtered review body currently says no vulnerabilities were found even though artifacts and status retain findings. Account for that mismatch before using this experiment as a publishing policy.</p><p>Eval sessions skip A/B enrollment.</p><h2 id="test-the-github-channel-carefully" tabindex="-1">Test the GitHub channel carefully <a class="header-anchor" href="#test-the-github-channel-carefully" aria-label="Permalink to &quot;Test the GitHub channel carefully&quot;">​</a></h2><p>The channel uses the host&#39;s Cursor account repository scope. It wakes on <code>opened</code> and <code>synchronize</code>, skips drafts, and posts its own GitHub Check.</p><p>Inspect its event surface:</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;"> events</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --json</span></span></code></pre></div><p>Replay reaches the full publishing path:</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:#24292E;--shiki-dark:#E1E4E8;">TEST_PR_URL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">https://github.com/your-org/allowlisted-test-repo/pull/123</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;"> replay</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$TEST_PR_URL</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opened</span></span></code></pre></div><p>Set <code>TEST_PR_URL</code> to a PR in the channel&#39;s configured repository allowlist. Run the command only against a PR intended for test reviews. It posts a GitHub Check and may post findings.</p><h2 id="inspect-the-eval-before-running-it" tabindex="-1">Inspect the eval before running it <a class="header-anchor" href="#inspect-the-eval-before-running-it" aria-label="Permalink to &quot;Inspect the eval before running it&quot;">​</a></h2><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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ../../factory/security-reviewer</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p>The case gates the review flow and prevents comment posting. It still fetches the live PR, so it needs GitHub access.</p><h2 id="build-another-staged-pipeline" tabindex="-1">Build another staged pipeline <a class="header-anchor" href="#build-another-staged-pipeline" aria-label="Permalink to &quot;Build another staged pipeline&quot;">​</a></h2><p>Use staged host orchestration when:</p><ul><li>each phase needs its own timeout and artifact,</li><li>model workers should run in bounded parallel,</li><li>later work can start as soon as partial results arrive,</li><li>a webhook must acknowledge before the work finishes, or</li><li>operators need live progress beyond one tool spinner.</li></ul><p>Keep external writes in finalization. Pass a <code>runId</code> between stages, journal progress before publishing, and make partial-worker failures visible in the result.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/github.html">GitHub</a></li><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/channels.html">Channels</a></li><li><a href="./../reference/playground.html">Playground</a></li><li><a href="./../storage.html">Storage</a></li><li><a href="./../ab.html">Live A/B metrics</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,71)])])}const g=t(r,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/example-agents_security-reviewer.md.74pPpWYj.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Run staged security reviews from GitHub events","description":"Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics.","frontmatter":{"title":"Run staged security reviews from GitHub events","description":"Orchestrate parallel reviewer agents, streamed triage, deterministic stages, live playground progress, durable sessions, and severity A/B metrics."},"headers":[],"relativePath":"example-agents/security-reviewer.md","filePath":"example-agents/security-reviewer.md"}'),r={name:"example-agents/security-reviewer.md"};function n(l,e,o,h,d,p){return a(),s("div",null,[...e[0]||(e[0]=[i("",71)])])}const g=t(r,[["render",n]]);export{u as __pageData,g as default};

package/dist/docs/assets/example-agents_slack-agent.md.D7Kdj5BV.js

@@ -1,5 +0,0 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel.","frontmatter":{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel."},"headers":[],"relativePath":"example-agents/slack-agent.md","filePath":"example-agents/slack-agent.md"}'),i={name:"example-agents/slack-agent.md"};function l(o,e,h,r,d,c){return s(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="put-a-minimal-agent-in-slack" tabindex="-1">Put a minimal agent in Slack <a class="header-anchor" href="#put-a-minimal-agent-in-slack" aria-label="Permalink to &quot;Put a minimal agent in Slack&quot;">​</a></h1><p>Slack agent is the smallest channel example. It has one runtime config, one instruction file, and one authored channel. A teammate mentions the agent, the local runtime harness runs a turn, and the answer returns to the same Slack thread.</p><p>Use it to learn the minimum needed for a Slack agent before adding tools, workflows, or a dedicated app.</p><p><a href="./../../examples/slack-agent/">Browse the Slack agent source.</a></p><h2 id="keep-the-slack-channel-small" tabindex="-1">Keep the Slack channel small <a class="header-anchor" href="#keep-the-slack-channel-small" aria-label="Permalink to &quot;Keep the Slack channel small&quot;">​</a></h2><p>Slack agent delegates transport details to the host connection. The authored file selects the account-linked transport, gives the agent a single-token router name and icon, and supplies suggested prompts.</p><p>The complete channel lives in <a href="../../examples/slack-agent/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a>. The framework supplies message intake, thread-scoped sessions, delivery, status updates, and suggested prompts.</p><h2 id="follow-a-slack-message" tabindex="-1">Follow a Slack message <a class="header-anchor" href="#follow-a-slack-message" aria-label="Permalink to &quot;Follow a Slack message&quot;">​</a></h2><ol><li>A user mentions the agent or sends the host app a direct message naming it.</li><li>The Slack relay selects this channel by its single-token <code>agentName</code>.</li><li>The Agent SDK maps the Slack channel and thread timestamp to a continuation key.</li><li>The local harness runs with <a href="./../../examples/slack-agent/agent/instructions.html"><code>instructions.md</code></a>.</li><li>The response returns to the triggering thread.</li><li>A later message in the same thread resumes the durable session.</li></ol><p>The prompt asks for concise threaded replies. It doesn&#39;t define domain policy or tool routing.</p><h2 id="map-the-slack-agent-files" tabindex="-1">Map the Slack agent files <a class="header-anchor" href="#map-the-slack-agent-files" aria-label="Permalink to &quot;Map the Slack agent files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/slack-agent/package.json"><code>package.json</code></a></td><td>Declares the example package and Agent SDK dependency.</td></tr><tr><td><a href="../../examples/slack-agent/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Names the agent and selects the model. The omitted <code>runtime</code> defaults to local.</td></tr><tr><td><a href="./../../examples/slack-agent/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Sets the always-on response style.</td></tr><tr><td><a href="../../examples/slack-agent/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Connects the signed-in host account to Slack.</td></tr><tr><td><a href="../../examples/slack-agent/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persists sessions and events with <code>cursorHostedStorage</code>.</td></tr></tbody></table><p>There are no authored tools, skills, MCP connections, subagents, schedules, hooks, A/B experiments, or evals. This small surface is the lesson.</p><h2 id="connect-the-host" tabindex="-1">Connect the host <a class="header-anchor" href="#connect-the-host" aria-label="Permalink to &quot;Connect the host&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential.</li><li>Slack connected through the selected channel transport.</li></ul><p>Sign in and confirm the active account:</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;"> login</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span></span></code></pre></div><p>The selected transport owns Slack credential setup. See the <a href="./../guides/slack.html">Slack guide</a> for account-linked and dedicated-app options.</p><h2 id="validate-and-start-the-server" tabindex="-1">Validate and start the server <a class="header-anchor" href="#validate-and-start-the-server" aria-label="Permalink to &quot;Validate and start the server&quot;">​</a></h2><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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/slack-agent</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/slack-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/slack-agent</span></span></code></pre></div><p>The dev command prints the playground URL. It also mounts the Slack channel and waits for relayed messages.</p><p>In Slack, address the configured host app and router name, then send:</p><blockquote><p><code>&lt;host-app mention&gt; &lt;router name&gt;</code> Explain the Agent SDK in three bullets.</p></blockquote><p>Reply in the generated thread:</p><blockquote><p>Make the second bullet simpler.</p></blockquote><p>The second message reaches the same session. You can open that session in the playground to inspect the received message, model events, final reply, and usage.</p><h2 id="test-without-slack" tabindex="-1">Test without Slack <a class="header-anchor" href="#test-without-slack" aria-label="Permalink to &quot;Test without Slack&quot;">​</a></h2><p>Every project gets the built-in HTTP channel even when no HTTP file exists. Run a one-shot turn through 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;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/slack-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Explain the Agent SDK simply.&quot;</span></span></code></pre></div><p>The same project also exposes an MCP endpoint. Since this agent has no server tools, its MCP surface contains <code>ask</code> and <code>check</code>, but not <code>call_tool</code>.</p><p>These automatic surfaces let you test the prompt from the CLI and let another agent delegate to it later. The authored Slack channel only changes how work arrives and where replies go.</p><h2 id="know-when-to-add-a-dedicated-app" tabindex="-1">Know when to add a dedicated app <a class="header-anchor" href="#know-when-to-add-a-dedicated-app" aria-label="Permalink to &quot;Know when to add a dedicated app&quot;">​</a></h2><p>An account-linked Slack transport is a fit for mentions, direct messages, thread continuity, and agent-branded replies. Move to a dedicated Socket Mode channel when you need:</p><ul><li>top-level channel watching,</li><li>interactive approval buttons,</li><li>a separate bot identity, or</li><li>Slack app events unsupported by the account-linked relay.</li></ul><p>Compare this example with <a href="./benny.html">Playbook router</a>, which adds allowlisted channel watching, and <a href="./weather-agent.html">Weather agent</a>, which adds approval buttons through a second Slack channel.</p><h2 id="turn-the-channel-into-your-own-slack-agent" tabindex="-1">Turn the channel into your own Slack agent <a class="header-anchor" href="#turn-the-channel-into-your-own-slack-agent" aria-label="Permalink to &quot;Turn the channel into your own Slack agent&quot;">​</a></h2><p>Copy the three authored files, then change:</p><ul><li><code>name</code> in <code>agent.ts</code> for the harness identity,</li><li><code>agentName</code> in <code>slack.ts</code> for the single-token router name,</li><li>the instructions for your domain, and</li><li>suggested prompts for the tasks teammates should try.</li></ul><p>Keep <code>agentName</code> free of whitespace. Use PascalCase for multiword names.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/channels.html">Channels</a></li><li><a href="./../reference/sessions.html">Sessions and streaming</a></li><li><a href="./../reference/playground.html">Playground</a></li></ul>`,42)])])}const g=a(i,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_slack-agent.md.D7Kdj5BV.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel.","frontmatter":{"title":"Put a minimal agent in Slack","description":"Use account-linked Slack routing, thread continuity, identity, and suggested prompts with one small channel."},"headers":[],"relativePath":"example-agents/slack-agent.md","filePath":"example-agents/slack-agent.md"}'),i={name:"example-agents/slack-agent.md"};function l(o,e,h,r,d,c){return s(),t("div",null,[...e[0]||(e[0]=[n("",42)])])}const g=a(i,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_weather-agent.md.CaGpmw3Y.js

@@ -1,25 +0,0 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function h(o,e,l,r,d,p){return t(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="explore-the-full-agent-sdk-surface-with-a-weather-agent" tabindex="-1">Explore the full Agent SDK surface with a weather agent <a class="header-anchor" href="#explore-the-full-agent-sdk-surface-with-a-weather-agent" aria-label="Permalink to &quot;Explore the full Agent SDK surface with a weather agent&quot;">​</a></h1><p>The weather agent is the broadest small example in the repository. It fetches live conditions and forecasts, converts units through MCP, writes notes in a session workspace, and runs from HTTP, Slack, a schedule, and the MCP endpoint.</p><p>Use this project when you want to see how the Agent SDK&#39;s filesystem pieces fit together before you design a larger agent.</p><p><a href="./../../examples/weather-agent/">Browse the weather agent source.</a></p><h2 id="see-the-runtime-features-together" tabindex="-1">See the runtime features together <a class="header-anchor" href="#see-the-runtime-features-together" aria-label="Permalink to &quot;See the runtime features together&quot;">​</a></h2><p>Most examples focus on one feature. Weather agent puts the major runtime features side by side:</p><table tabindex="0"><thead><tr><th>Capability</th><th>Source</th><th>Role</th></tr></thead><tbody><tr><td>Root config and instructions</td><td><a href="../../examples/weather-agent/agent/agent.ts"><code>agent/agent.ts</code></a>, <a href="./../../examples/weather-agent/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Select the cloud runtime and route each request.</td></tr><tr><td>Server tools</td><td><a href="./../../examples/weather-agent/agent/tools/"><code>agent/tools/</code></a></td><td>Fetch Open-Meteo data and call MCP from the serve host.</td></tr><tr><td>Agent tool</td><td><a href="../../examples/weather-agent/agent/tools/save_weather_note.ts"><code>save_weather_note.ts</code></a></td><td>Run a Python script inside the session workspace.</td></tr><tr><td>Stdio MCP</td><td><a href="../../examples/weather-agent/agent/mcp-connections/units.ts"><code>units.ts</code></a>, <a href="../../examples/weather-agent/agent/mcp-connections/probe.ts"><code>probe.ts</code></a></td><td>Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript <code>execute</code> functions.</td></tr><tr><td>Custom HTTP</td><td><a href="../../examples/weather-agent/agent/channels/webhook.ts"><code>webhook.ts</code></a></td><td>Start a turn or call MCP without a model turn.</td></tr><tr><td>Slack</td><td><a href="../../examples/weather-agent/agent/channels/slack.ts"><code>slack.ts</code></a>, <a href="../../examples/weather-agent/agent/channels/slack-app.ts"><code>slack-app.ts</code></a></td><td>Compare account-linked chat with a dedicated app.</td></tr><tr><td>Skill and subagent</td><td><a href="./../../examples/weather-agent/agent/skills/forecast.html"><code>forecast.md</code></a>, <a href="./../../examples/weather-agent/agent/subagents/researcher/"><code>researcher/</code></a></td><td>Load a procedure on demand or delegate broad research.</td></tr><tr><td>Schedule and hooks</td><td><a href="./../../examples/weather-agent/agent/schedules/heartbeat.html"><code>heartbeat.md</code></a>, <a href="../../examples/weather-agent/agent/hooks/audit.ts"><code>audit.ts</code></a>, <a href="../../examples/weather-agent/agent/hooks/journal.ts"><code>journal.ts</code></a></td><td>Start recurring tasks, log usage, and save turn summaries.</td></tr><tr><td>A/B and evals</td><td><a href="../../examples/weather-agent/agent/ab.ts"><code>agent/ab.ts</code></a>, <a href="./../../examples/weather-agent/evals/"><code>evals/</code></a></td><td>Compare a sticky variant and protect tool routing with regression cases.</td></tr></tbody></table><h2 id="follow-one-request" tabindex="-1">Follow one request <a class="header-anchor" href="#follow-one-request" aria-label="Permalink to &quot;Follow one request&quot;">​</a></h2><p>A current-weather question takes this path:</p><ol><li>The built-in HTTP channel, Slack, or the custom <code>/report</code> route creates a durable session.</li><li><code>instructions.md</code> tells the model to call <code>get_weather</code> instead of guessing.</li><li>The server tool geocodes the city, fetches Open-Meteo, validates the response, and returns normalized fields.</li><li>The agent writes a short answer. The Agent SDK records every event in the session stream.</li><li>The audit hook observes <code>turn.completed</code>. If the session joined the A/B experiment, the collector updates its metrics too.</li></ol><p>Forecasts route to <code>get_forecast</code>. Unit conversions route to <code>convert_temperature</code>, which calls the <code>units</code> MCP server through <code>ctx.host.mcp</code>. Climate history and broad comparisons route to the <code>researcher</code> subagent.</p><h2 id="prepare-the-example" tabindex="-1">Prepare the example <a class="header-anchor" href="#prepare-the-example" aria-label="Permalink to &quot;Prepare the example&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential.</li><li>Network access to Open-Meteo.</li><li>Python 3 for <code>save_weather_note</code>.</li></ul><p>The project mounts an account-linked Slack channel. The Agent SDK checks the connection at startup, so sign in even when you plan to call a deterministic tool.</p><p>The optional dedicated Slack app also needs a token pair. <code>agent-sdk slack create --dir examples/weather-agent</code> provisions the app and writes the tokens for you (see the <a href="./../guides/slack.html#set-it-up">Slack guide</a>); with hand-minted tokens, export them instead:</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;"> WEATHER_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;"> WEATHER_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>
-<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;"> WEATHER_AGENT</span></span></code></pre></div><p>Without those two tokens, the dedicated channel stays idle. The account-linked channel still works.</p><h2 id="inspect-before-running" tabindex="-1">Inspect before running <a class="header-anchor" href="#inspect-before-running" aria-label="Permalink to &quot;Inspect before running&quot;">​</a></h2><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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p><code>validate</code> should pass. <code>info</code> and <code>eval --list</code> should match the capabilities described above.</p><h2 id="call-the-typed-tools" tabindex="-1">Call the typed tools <a class="header-anchor" href="#call-the-typed-tools" aria-label="Permalink to &quot;Call the typed tools&quot;">​</a></h2><p>Start with the current-weather server tool:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_weather</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;city&quot;:&quot;New York City&quot;}&#39;</span></span></code></pre></div><p><code>defineTool</code> gives the input a Zod schema. The Agent SDK validates the JSON before <code>execute</code> runs. The result includes the matched place, condition, temperature, humidity, wind, gusts, and precipitation.</p><p>Try the forecast:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get_forecast</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;city&quot;:&quot;Lisbon&quot;,&quot;days&quot;:5}&#39;</span></span></code></pre></div><p>The tool accepts one to seven days. Shared Open-Meteo code lives under <code>agent/lib/</code>, so the Agent SDK imports it without discovering another tool.</p><h2 id="compare-server-and-agent-execution" tabindex="-1">Compare server and agent execution <a class="header-anchor" href="#compare-server-and-agent-execution" aria-label="Permalink to &quot;Compare server and agent execution&quot;">​</a></h2><p>Most weather tools use the default <code>execution: &quot;server&quot;</code>. Their TypeScript runs inside the serve host and can reach <code>ctx.host</code> services.</p><p><code>save_weather_note</code> uses <code>execution: &quot;agent&quot;</code> instead. The Agent SDK materializes its script into the agent environment. The script reads JSON from stdin and appends to <code>weather-notes.md</code> in that session&#39;s workspace:</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;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Save a note that Boston is cold and windy.&quot;</span></span></code></pre></div><p>Each session gets its own workspace. Saving a note doesn&#39;t edit the authored example.</p><p>This split matters on cloud. Server tools stay on the Agent SDK host. Agent tools run inside the cloud workspace.</p><h2 id="verify-tool-execution-on-the-agent-vm" tabindex="-1">Verify tool execution on the agent VM <a class="header-anchor" href="#verify-tool-execution-on-the-agent-vm" aria-label="Permalink to &quot;Verify tool execution on the agent VM&quot;">​</a></h2><p>Ask the agent to call <code>probe_cloud_tool</code> on the <code>probe</code> MCP server. <code>agent/mcp-connections/probe.ts</code> authors that tool as TypeScript. The Agent SDK packages it as stdio MCP so a cloud VM with no checkout of this example can still run it. The model lists the server and calls the tool; it does not write a <code>.sh</code>.</p><p>A real call writes <code>vm-tool-observations/&lt;id&gt;.json</code> in the agent cwd and returns hostname, cwd, and pid. Stream events show <code>probe:probe_cloud_tool</code>, not <code>shell</code>.</p><p>A local tool script or a marker under <code>probes/</code> means the model invented a substitute.</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;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Test custom tool execution from this cloud agent. Call probe_cloud_tool.&quot;</span></span></code></pre></div><h2 id="use-mcp-connections-in-three-places" tabindex="-1">Use MCP connections in three places <a class="header-anchor" href="#use-mcp-connections-in-three-places" aria-label="Permalink to &quot;Use MCP connections in three places&quot;">​</a></h2><p><code>agent/mcp-connections/units.ts</code> starts a local stdio server. The filename makes its server name <code>units</code>. The Agent SDK exposes it to:</p><ul><li>the model as MCP tools,</li><li>server tools through <code>ctx.host.mcp</code>, and</li><li>channel handlers through <code>host.mcp</code>.</li></ul><p><code>probe</code> is a second stdio connection. Its tools are TypeScript <code>execute</code> functions; the Agent SDK packages them so a cloud VM can spawn the server without this checkout. The model calls <code>probe_cloud_tool</code> directly; no host tool wraps it.</p><p><code>convert_temperature</code> demonstrates the server-tool path:</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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> convert_temperature</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;value&quot;:72,&quot;from&quot;:&quot;F&quot;}&#39;</span></span></code></pre></div><p>The custom channel demonstrates the handler path. Start the dev server:</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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span></code></pre></div><p>Then call MCP deterministically through <code>/convert</code>:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/convert</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;value&quot;:20,&quot;from&quot;:&quot;C&quot;}&#39;</span></span></code></pre></div><p>No model chooses a tool in this route. The handler calls the MCP server and returns its result.</p><h2 id="keep-conversation-state-in-a-custom-channel" tabindex="-1">Keep conversation state in a custom channel <a class="header-anchor" href="#keep-conversation-state-in-a-custom-channel" aria-label="Permalink to &quot;Keep conversation state in a custom channel&quot;">​</a></h2><p><code>POST /report</code> starts a model turn and waits for it:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What is the weather in Paris?&quot;}&#39;</span></span></code></pre></div><p>The response includes a <code>key</code>. Send it back on the next request to continue the same session:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;How about tomorrow?&quot;,&quot;key&quot;:&quot;&lt;key&gt;&quot;}&#39;</span></span></code></pre></div><p>This is the custom-channel version of a continuation token. See <a href="./../guides/webhooks.html">webhooks and custom channels</a> for route schemas, authentication, and asynchronous handlers.</p><h2 id="load-procedures-and-delegate-research" tabindex="-1">Load procedures and delegate research <a class="header-anchor" href="#load-procedures-and-delegate-research" aria-label="Permalink to &quot;Load procedures and delegate research&quot;">​</a></h2><p>The forecast skill gives the root agent an on-demand procedure. The Agent SDK advertises the skill&#39;s description, then the harness loads its content when the request matches.</p><p>The <code>researcher</code> directory is an SDK subagent. Its description tells the parent when to delegate. It inherits the parent&#39;s execution surface, but gets its own instructions:</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;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Compare record summer temperatures across Paris, London, and Rome.&quot;</span></span></code></pre></div><p>Use a skill when the same agent needs a procedure. Use a subagent when the parent should hand a bounded task to a specialist. The <a href="./../reference/subagents.html">subagents reference</a> explains the current inheritance limits.</p><h2 id="trigger-the-schedule-and-inspect-the-hook" tabindex="-1">Trigger the schedule and inspect the hook <a class="header-anchor" href="#trigger-the-schedule-and-inspect-the-hook" aria-label="Permalink to &quot;Trigger the schedule and inspect the hook&quot;">​</a></h2><p>The heartbeat schedule runs at 09:00 UTC on weekdays. Automatic schedule timers stay off under <code>--dev</code>, so dispatch it manually:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  http://127.0.0.1:3000/weather-agent/v1/dev/schedules/heartbeat</span></span></code></pre></div><p>It creates a task session to check San Francisco, New York, and London. The audit hook logs usage after each completed turn. Hooks observe recorded events; their failures don&#39;t fail the turn.</p><h2 id="measure-variants-and-regressions" tabindex="-1">Measure variants and regressions <a class="header-anchor" href="#measure-variants-and-regressions" aria-label="Permalink to &quot;Measure variants and regressions&quot;">​</a></h2><p>The <code>weather-tool-efficiency</code> A/B experiment assigns sessions by a sticky hash:</p><ul><li><code>control</code> returns current conditions in Fahrenheit.</li><li><code>treatment</code> adds a brief Celsius instruction and changes <code>get_weather</code> to return Celsius fields.</li></ul><p>Samples and aggregate snapshots persist under the project state directory. The treatment only changes current conditions; <code>get_forecast</code> still returns Fahrenheit. Treat the branch as an example of <code>ctx.session.abs</code>, not a complete unit policy.</p><p>List and run the evals:</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;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</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;"> examples/weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The suite covers weather and forecast routing, the local converter, workspace notes, and the VM-side probe.</p><h2 id="turn-the-weather-tour-into-your-own-agent" tabindex="-1">Turn the weather tour into your own agent <a class="header-anchor" href="#turn-the-weather-tour-into-your-own-agent" aria-label="Permalink to &quot;Turn the weather tour into your own agent&quot;">​</a></h2><p>Keep the shape and replace the domain:</p><ul><li>Swap Open-Meteo tools for your typed service clients.</li><li>Keep deterministic transforms behind direct server tools or MCP.</li><li>Use an agent tool only when code must run in the agent workspace.</li><li>Put reusable procedures in skills and narrow specialist work into subagents.</li><li>Add a channel only when the external surface needs its own identity, continuation key, or delivery behavior.</li></ul><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/connections.html">MCP connections</a></li><li><a href="./../guides/human-in-the-loop.html">Human-in-the-loop approvals</a></li><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/schedules.html">Schedules and reminders</a></li><li><a href="./../evals.html">Evals</a></li><li><a href="./../ab.html">Live A/B metrics</a></li></ul>`,77)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_weather-agent.md.CaGpmw3Y.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent.","frontmatter":{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."},"headers":[],"relativePath":"example-agents/weather-agent.md","filePath":"example-agents/weather-agent.md"}'),n={name:"example-agents/weather-agent.md"};function h(o,e,l,r,d,p){return t(),a("div",null,[...e[0]||(e[0]=[i("",77)])])}const g=s(n,[["render",h]]);export{k as __pageData,g as default};

package/dist/docs/assets/guides_cloud-runtime.md.BnvjPiia.js

@@ -1,9 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="cloud-runtime" tabindex="-1">Cloud runtime <a class="header-anchor" href="#cloud-runtime" aria-label="Permalink to &quot;Cloud runtime&quot;">​</a></h1><p>By default, turns execute on the Cursor SDK&#39;s local harness, on the same machine as the server. Set <code>runtime: &quot;cloud&quot;</code> and turns execute on Cursor cloud agents instead. They&#39;re ephemeral VMs that carry a repo checkout, run <code>gh</code>, <code>git</code>, and tests for real, and scale past what one host&#39;s disk and CPU can do. The serve host keeps handling routing, host preparation, sessions, and bookkeeping.</p><p>A canonical use is a PR driver whose triage runs on cloud VMs. The patterns in this guide come from running one against real PR traffic.</p><h2 id="when-to-switch" tabindex="-1">When to switch <a class="header-anchor" href="#when-to-switch" aria-label="Permalink to &quot;When to switch&quot;">​</a></h2><p>A guideline from running PR agents at scale: per-PR worktrees on the serve host don&#39;t scale to hundreds of engineers opening PRs. When the job needs a repo checkout at scale, use cloud. The signals:</p><ul><li>The agent must run repo commands (tests, builds, <code>git</code>) against many different refs concurrently.</li><li>Turns are long and heavy, and you don&#39;t want them competing with the server for resources.</li><li>The work product is a PR or branch the VM can push, not a local file.</li></ul><p>Stay local when the agent is conversational, tool-driven against APIs, or works over host-prepared evidence. Local turns are cheaper, start faster, and support the full authored surface.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to &quot;Configure it&quot;">​</a></h2><p>Cloud runtime is two fields on the agent config.</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;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  runtime: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;cloud&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cloud: {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/org/repo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;main&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // env / envVars / … forwarded to the Cursor SDK</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>The host must be signed in (<code>agent-sdk login</code> or <code>CURSOR_API_KEY</code>).</p><div class="important custom-block github-alert"><p class="custom-block-title">IMPORTANT</p><p>Cloud agents run against the Cursor backend under the signed-in account, and every wake spends real cloud-agent budget. Decide explicitly what may trigger one.</p></div><h2 id="what-changes-on-cloud" tabindex="-1">What changes on cloud <a class="header-anchor" href="#what-changes-on-cloud" aria-label="Permalink to &quot;What changes on cloud&quot;">​</a></h2><p>Cloud turns run on a VM without your authored files, so the runtime mapping shifts:</p><table tabindex="0"><thead><tr><th>Folder or file</th><th>Local runtime</th><th>Cloud runtime</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code> in the session workspace</td><td>prepended to the first prompt</td></tr><tr><td>Server tools (<code>execution: &quot;server&quot;</code>)</td><td>in-process SDK custom tools</td><td>authenticated HTTP MCP back to the AgentSDK host, when <code>--public-url</code> or <code>--cloud-tools-url</code> is set</td></tr><tr><td>Agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace</td><td>catalog + script bodies on the first prompt</td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/</code> in the workspace</td><td>native discovery after the first turn, from the hosted store or the signed-in account</td></tr><tr><td><code>mcp-connections/*.ts</code></td><td>SDK <code>mcpServers</code></td><td>SDK <code>mcpServers</code> (peers need <code>--public-url</code>)</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>seeded into the session workspace</td><td>ignored</td></tr><tr><td>Tool approvals (<code>needsApproval</code>)</td><td>supported</td><td>not supported; keep approval-gated tools on local turns</td></tr></tbody></table><p>Authored skills are discovered natively after the first cloud turn, using the hosted store or the signed-in account.</p><p>Approvals are a local-runtime contract. On cloud, a <code>needsApproval</code> tool call rides one HTTP MCP request from the VM, and a parked call would hold that request open until it times out; there is no durable approval flow for cloud turns.</p><p>Peer MCP connections need <code>--public-url</code> for cloud turns. Without one, peers are omitted and the server warns at startup.</p><h2 id="hybrid-local-agent-cloud-sessions" tabindex="-1">Hybrid: local agent, cloud sessions <a class="header-anchor" href="#hybrid-local-agent-cloud-sessions" aria-label="Permalink to &quot;Hybrid: local agent, cloud sessions&quot;">​</a></h2><p>A local-runtime agent can still open cloud-attached sessions per send. Channel handlers may pass a <code>cloud</code> block (repos pinned to a PR ref, say) in <code>send</code> options, and Slack handlers may return <code>cloud</code> from a mention hook. A PR driver works this way: chat stays local, and the <code>drive</code> flow attaches the PR to a cloud VM. The agent-level <code>cloud</code> config is the base that per-session options merge over.</p><h2 id="patterns-that-hold-up" tabindex="-1">Patterns that hold up <a class="header-anchor" href="#patterns-that-hold-up" aria-label="Permalink to &quot;Patterns that hold up&quot;">​</a></h2><p>These come from running a PR driver against real PR traffic:</p><ul><li>One cloud session per unit of work, keyed with a stable continuation token (<code>pr:owner/repo#N</code>) so every wake lands on the same conversation.</li><li>Keep the host deterministic: fetch briefs and metadata on the host, send the VM a compact prompt, and let the VM re-read source of truth with its own <code>gh</code> and <code>git</code> instead of trusting payload snapshots.</li><li>Limit exposure: add repository allowlists on webhook channels, because every wake spends the account&#39;s budget.</li></ul><h2 id="verify-cloud-agents" tabindex="-1">Verify cloud agents <a class="header-anchor" href="#verify-cloud-agents" aria-label="Permalink to &quot;Verify cloud agents&quot;">​</a></h2><p><code>agent-sdk run</code> and <code>eval</code> work unchanged. The trajectory records the same event vocabulary plus <code>agent.bound</code> with the cloud URL, so you can open the cloud conversation for any session. Cloud turns take minutes. Pass generous <code>--timeout-ms</code> values, and keep curl timeouts long when driving channels directly.</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><p>Continue with these pages:</p><ul><li><a href="./../reference/agent-config.html">Agent config</a>: the <code>runtime</code> and <code>cloud</code> fields</li><li><a href="./github.html">GitHub guide</a>: the webhook patterns that pair with cloud triage</li></ul>`,28)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/guides_cloud-runtime.md.BnvjPiia.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up.","frontmatter":{"title":"Cloud runtime","description":"Run turns on Cursor cloud agents instead of the local harness: when to switch, what changes, and the patterns that hold up."},"headers":[],"relativePath":"guides/cloud-runtime.md","filePath":"guides/cloud-runtime.md"}'),n={name:"guides/cloud-runtime.md"};function i(r,e,d,l,c,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",28)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

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

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

package/dist/docs/assets/index.md.B-lVR4wT.js

@@ -1,5 +0,0 @@
-import{_ as t,c as a,o as i,ag as s}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals.","frontmatter":{"title":"Agent SDK documentation","description":"Build and run Cursor agents with tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),n={name:"index.md"};function r(l,e,o,h,d,c){return i(),a("div",null,[...e[0]||(e[0]=[s(`<h1 id="agent-sdk-documentation" tabindex="-1">Agent SDK documentation <a class="header-anchor" href="#agent-sdk-documentation" aria-label="Permalink to &quot;Agent SDK documentation&quot;">​</a></h1><p>Use the Agent SDK to define Cursor agents in TypeScript and Markdown. See <a href="./reference/project-layout.html">Project layout</a> for the directory structure.</p><p>Use Node 22.13 or newer. Bun isn&#39;t supported.</p><p>Create a project:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./my-agent</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>If <code>agent-sdk</code> isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><p>Open the docs locally:</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;">npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> docs</span></span></code></pre></div><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to the Agent SDK</td><td><a href="./quickstart.html">Quickstart</a> (PR reviewer), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Turning a Cursor Automation into a project</td><td><a href="./guides/convert-automation.html">Convert a Cursor Automation</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Starting from a packaged template</td><td><a href="./templates/demo.html">Demo</a>, <a href="./templates/security-reviewer.html">Security reviewer</a>, <a href="./templates/triage.html">Triage</a>, or <a href="./templates/agentic-owners.html">Agentic Owners</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Driving PRs from a cloud VM</td><td><a href="./templates/pr-autofixer.html">PR autofixer template</a></td></tr><tr><td>Driving an agent from Linear (or another tracker)</td><td><a href="./guides/webhooks.html#example-linear-as-the-control-plane">Webhooks guide: Linear example</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="documentation" tabindex="-1">Documentation <a class="header-anchor" href="#documentation" aria-label="Permalink to &quot;Documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR reviewer that classifies changes by complexity and handles GitHub webhook events.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./guides/convert-automation.html">Convert a Cursor Automation</a>: export a dashboard Automation into an Agent SDK project.</li><li><a href="./concepts.html">Concepts</a>: agent discovery, sessions, channels, runtimes, and observability.</li></ul><p><strong>Templates</strong></p><ul><li><a href="./templates/demo.html">Record a walkthrough from a collected PR</a>: host collects the PR, the model records, then comments.</li><li><a href="./templates/security-reviewer.html">Security reviewer</a>: review pull requests for exploitable bugs and post one comment.</li><li><a href="./templates/triage.html">Triage Linear or Jira issues in place</a>: classify existing tickets and comment on them.</li><li><a href="./templates/agentic-owners.html">Review pull requests with owners policies</a>: request owners and approve changes allowed by repository policy.</li><li><a href="./templates/pr-autofixer.html">Fix pull requests on a Cursor cloud VM</a></li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./storage.html">Storage</a>: point durable storage at a backend you own with <code>defineStorage</code>.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: measure and improve an agent iteratively.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: trigger the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and <code>--store</code> them on hosted deployments.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li><li><a href="./guides/opentelemetry.html">OpenTelemetry</a>: push session, turn, and tool traces to an OTLP collector you run.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare the example agents by runtime, channels, tools, and state.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/oncall.html">Alert investigator</a>: watch a Slack alerts channel and pin a self-rechecking investigation to every alert thread.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: diagnose common failures by symptom.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>Docs use <code>agent-sdk &lt;command&gt;</code>. If it isn&#39;t on <code>PATH</code>, use <code>npx @cursor/july &lt;command&gt;</code>.</p><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Sign in to Cursor or set <code>CURSOR_API_KEY</code>:</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;"> login</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span></span></code></pre></div><p>Confirm <code>agent-sdk whoami</code> shows the expected account.</p><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><ul><li>Package reference: <a href="./../README.html"><code>README.md</code></a></li><li>Coding-agent workflows: <a href="./../skills/"><code>skills/</code></a></li></ul>`,33)])])}const g=t(n,[["render",r]]);export{u as __pageData,g as default};

package/dist/docs/assets/reference_http-api.md.C68BERYr.js

@@ -1,11 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,h,c){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="http-api-reference" tabindex="-1">HTTP API reference <a class="header-anchor" href="#http-api-reference" aria-label="Permalink to &quot;HTTP API reference&quot;">​</a></h1><p>Agent SDK hosts expose the same public HTTP surface. In the default multi-agent layout each agent is namespaced under its slug (<code>/&lt;slug&gt;/v1/session</code>, <code>/&lt;slug&gt;/playground</code>), with host-level routes at the root. With <code>--mode single</code>, one agent serves the same surface unslugged (<code>/v1/*</code>).</p><p>Unless noted otherwise, routes run the agent&#39;s HTTP auth chain: the default is <code>localDevStrict()</code> (loopback only), replaced by <code>bearerAuth</code> under <code>--bearer-token</code> or <code>allowAll()</code> under <code>--allow-anonymous</code>. Session routes also require the caller to be the session&#39;s owner (<code>403</code> otherwise). Errors return JSON <code>{ ok: false, error: &quot;&lt;code&gt;&quot;, message? }</code> with a matching HTTP status.</p><h2 id="host-level-routes-multi-agent-mode" tabindex="-1">Host-level routes (multi-agent mode) <a class="header-anchor" href="#host-level-routes-multi-agent-mode" aria-label="Permalink to &quot;Host-level routes (multi-agent mode)&quot;">​</a></h2><p>These routes live at the host root, above any agent. The two index routes exist only while the playground is enabled (<code>--no-playground</code> removes them) and run no auth. The documentation site is mounted in both layouts and removed by <code>--no-docs</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /</code></td><td>A web index of every mounted agent, linking to playgrounds (playground only)</td></tr><tr><td><code>GET /v1/agents</code></td><td>The JSON index of mounted agents (playground only, no auth)</td></tr><tr><td><code>GET /docs</code>, <code>GET /docs/*</code></td><td>This documentation, served as a static site (both layouts, no auth)</td></tr><tr><td><code>GET /v1/health</code></td><td>Host-level liveness, no auth</td></tr></tbody></table><h2 id="start-a-session" tabindex="-1">Start a session <a class="header-anchor" href="#start-a-session" aria-label="Permalink to &quot;Start a session&quot;">​</a></h2><p><code>POST /v1/session</code> opens a durable conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</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;">/v1/session</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</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;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends.</p><p>Expect <code>409</code> on a stale token or a task session. Task sessions do not accept follow-ups. Expect <code>403</code> when the caller is not the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#which-events-can-i-stream">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="session-cost" tabindex="-1">Session cost <a class="header-anchor" href="#session-cost" aria-label="Permalink to &quot;Session cost&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/cost</code> returns the session&#39;s cost report: per-turn token usage and the engine&#39;s estimated cost, folded from <code>turn.completed</code> events. It runs the same owner check as the other session routes and returns <code>404</code> for an unknown session. The <a href="./cli.html#cost"><code>agent-sdk cost</code></a> command reports the same data.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./../guides/human-in-the-loop.html">Human-in-the-loop</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</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;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;input&quot;:{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}}&#39;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;toolName&quot;:&quot;inspect_pr&quot;,&quot;callId&quot;:&quot;tool_inspect_pr_…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><p>It runs an authored server tool in-process: schema-validated, no model turn. An optional <code>&quot;sessionId&quot;</code> in the body runs it inside an existing session and records it on that session&#39;s stream (<code>409 session_busy</code> while a turn runs). Agent-execution tools are rejected with <code>400</code>, and unknown tools with <code>404</code> and the list of available names. For the semantics, see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>.</p><h2 id="discovery" tabindex="-1">Discovery <a class="header-anchor" href="#discovery" aria-label="Permalink to &quot;Discovery&quot;">​</a></h2><p>These read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics</td></tr><tr><td><code>GET /v1/health</code></td><td>Per-agent liveness, no auth</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Recent server log lines, with a polling cursor</td></tr><tr><td><code>GET /v1/abs</code></td><td><a href="./../ab.html">Live A/B metrics</a>: per-session assignments and aggregate arm totals</td></tr></tbody></table><h2 id="artifacts" tabindex="-1">Artifacts <a class="header-anchor" href="#artifacts" aria-label="Permalink to &quot;Artifacts&quot;">​</a></h2><p>Two routes read durable artifacts tagged by <code>ctx.artifacts</code> or <code>tag_artifact</code>. See <a href="./artifacts.html">Artifacts</a>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/artifacts</code></td><td>List artifacts as <code>{ artifacts }</code>, newest-updated first. Filter with <code>?kind=</code>, <code>?sessionId=</code>, and <code>?limit=</code> (a positive integer)</td></tr><tr><td><code>GET /v1/artifacts/:id/content</code></td><td>Download one artifact&#39;s file or blob payload. Served as an attachment, never rendered inline; <code>404</code> when the artifact is unknown or carries no content</td></tr></tbody></table><p>Session ownership applies the same way as <code>GET /v1/sessions</code>: under <code>serve --dev</code> on loopback (or <code>--allow-anonymous</code>) the list spans all principals, while bearer or custom channel auth keeps strict per-principal isolation.</p><h2 id="custom-channel-routes" tabindex="-1">Custom channel routes <a class="header-anchor" href="#custom-channel-routes" aria-label="Permalink to &quot;Custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with the methods, paths, and Zod schemas the channel declared (a <code>POST /&lt;slug&gt;/v1/channels/drive</code> route, say). Bodies are validated before handlers run (<code>400</code> on schema violations), and each channel&#39;s auth chain applies. The GitHub channel verifies <code>X-Hub-Signature-256</code> when a secret is configured. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p><code>/v1/mcp</code> serves the Model Context Protocol over streamable HTTP (stateless; POST carries the protocol, and GET/DELETE return spec-compliant 405s). The tools are <code>ask</code> (delegate a message, bounded waits), <code>check</code> (poll a running session), and <code>call_tool</code> (deterministic server-tool passthrough, present when the agent has server tools). The route runs the same auth chain as the session API. See <a href="./../guides/agent-to-agent.html">Agent-to-agent</a>.</p><p><code>/v1/mcp/tools</code> is a second stateless MCP endpoint exposing only the agent&#39;s deterministic server tools. Hosted cloud turns call back into it through the URL configured by <code>serve --cloud-tools-url</code>. Unlike <code>/v1/mcp</code>, it runs the CLI-level auth chain (loopback, bearer, or anonymous), not any authored channel auth.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>The playground Evals tab and <code>agent-sdk eval --prod</code> / <code>--url</code> use these:</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered eval datapoints and project config</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots, newest first</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start an eval run (<code>{filterIds?, tags?}</code>); <code>202</code> with a snapshot (<code>runId</code> is the Eval ID), <code>404</code> when nothing matches, <code>409</code> when one is running</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Poll a run&#39;s progress</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel a running batch; <code>200</code> with snapshot, <code>404</code> unknown, <code>409</code> when not running</td></tr></tbody></table><p>Eval runs are asynchronous. Poll the run route for case progress and the final <code>completed</code> or <code>failed</code> status. Batch errors appear on the snapshot returned by the poll. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics. When both fields are present, a case must match one entry from each field. Listed runs persist across restarts when storage is configured; see <a href="./../storage.html#eval-and-a-b-tables">Storage</a>. Otherwise they are process-memory only.</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes are the only way they run, which keeps iteration deterministic.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the playground (omitted with <code>--no-playground</code>). It calls the JSON API above and has no privileged surface.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Error responses use a small, consistent set of status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning here</th></tr></thead><tbody><tr><td><code>400</code></td><td>Schema-invalid body or query, agent-execution tool called on the host, malformed request</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>Authenticated, but not the session owner</td></tr><tr><td><code>404</code></td><td>Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request</td></tr><tr><td><code>405</code></td><td>Wrong method (GET on the MCP endpoint, say)</td></tr><tr><td><code>409</code></td><td>Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress</td></tr><tr><td><code>202</code></td><td>Accepted for background work (GitHub <code>{ task }</code> hooks, eval runs)</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><p>Continue with these pages:</p><ul><li><a href="./sessions.html">Sessions and streaming</a>: the handles and events these routes traffic in</li><li><a href="./channels.html">Channels</a>: authoring your own routes</li><li><a href="./../deployment.html">Deployment</a>: auth on real hosts</li></ul>`,61)])])}const k=t(n,[["render",d]]);export{u as __pageData,k as default};

package/dist/docs/assets/reference_http-api.md.C68BERYr.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,ag as o}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,h,c){return a(),s("div",null,[...e[0]||(e[0]=[o("",61)])])}const k=t(n,[["render",d]]);export{u as __pageData,k as default};