@cursor/july 0.1.35 → 0.1.36

package/dist/docs/assets/{example-agents_codeowners-review.md.D6ay4nvf.js → example-agents_codeowners-review.md.BU2ZXLf-.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision.","frontmatter":{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision."},"headers":[],"relativePath":"example-agents/codeowners-review.md","filePath":"example-agents/codeowners-review.md"}'),r={name:"example-agents/codeowners-review.md"};function o(n,e,l,d,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="route-pr-reviews-by-code-ownership" tabindex="-1">Route PR reviews by code ownership <a class="header-anchor" href="#route-pr-reviews-by-code-ownership" aria-label="Permalink to &quot;Route PR reviews by code ownership&quot;">​</a></h1><p>Codeowners review gives each part of a codebase its own review. A CODEOWNERS-style table maps changed paths to review areas; each area has a markdown playbook with the team&#39;s rules for that domain; and one <code>area-reviewer</code> subagent runs per routed area, in parallel. A billing change gets the billing review, a migration gets the migration review, and an author&#39;s personal style rides along as advisory notes. The lead aggregates: approve only when every area approves.</p><p>Use this project when review quality depends on domain-specific values instead of one generic checklist.</p><p><a href="./../../examples/codeowners-review/">Browse the codeowners review source.</a></p><h2 id="keep-routing-in-code-and-judgment-in-playbooks" tabindex="-1">Keep routing in code and judgment in playbooks <a class="header-anchor" href="#keep-routing-in-code-and-judgment-in-playbooks" aria-label="Permalink to &quot;Keep routing in code and judgment in playbooks&quot;">​</a></h2><p>The pipeline separates three concerns:</p><ul><li><code>reviews/REVIEWERS</code> routes. Host code matches every changed path against the table; every matching rule applies, and unmatched paths fall back to the <code>general</code> playbook. Routing is glob code with unit tests, not model judgment.</li><li><code>reviews/&lt;area&gt;.md</code> judges. Each playbook is a severity-ordered rule list the team owns: billing mandates integer cents and idempotent webhooks, migrations forbid destructive DDL beside code changes, background jobs demand idempotency and dead-letter paths.</li><li>Subagents review. The lead reads nothing but the manifest and routes; each <code>area-reviewer</code> reads one playbook plus its files&#39; diff hunks and returns a mechanical verdict: request changes on any High finding or two Mediums.</li></ul><p>Personal styles extend the same mechanism. <code>reviews/people/&lt;login&gt;.md</code> attaches automatically, as advisory notes, whenever that person authors the PR. Adding an area or a style is a markdown file plus at most one routing line.</p><h2 id="follow-a-review" tabindex="-1">Follow a review <a class="header-anchor" href="#follow-a-review" aria-label="Permalink to &quot;Follow a review&quot;">​</a></h2><ol><li>A PR arrives: a GitHub <code>pull_request</code> event, a chat message, or a bundled fixture reference.</li><li><code>prepare_review</code> fetches metadata and the diff with the host <code>gh</code> CLI, routes every changed file, and writes the <code>pr/</code> evidence tree: <code>MANIFEST.md</code>, <code>ROUTES.md</code>, <code>diff.patch</code>, and a copy of each matched playbook.</li><li>The lead follows the <code>review-process</code> skill and issues one <code>area-reviewer</code> delegation per routed area, plus one per personal style, all in one step so they run in parallel.</li><li>Each reviewer reads its playbook, reviews only its files, and returns a verdict line with at most three findings.</li><li>The lead aggregates per-area sections and the overall verdict: APPROVE only when every non-advisory area approved.</li></ol><p>Nothing posts to GitHub. Verdicts live in the session; the <a href="./approval-buddy.html">Approval Buddy guide</a> shows how to wire a real APPROVE and commit statuses on top of the same shape.</p><h2 id="map-the-review-files" tabindex="-1">Map the review files <a class="header-anchor" href="#map-the-review-files" aria-label="Permalink to &quot;Map the review files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="./../../examples/codeowners-review/reviews/REVIEWERS.html"><code>reviews/REVIEWERS</code></a></td><td>Routes path patterns to review areas.</td></tr><tr><td><a href="./../../examples/codeowners-review/reviews/"><code>reviews/</code></a></td><td>Holds the area playbooks and <code>people/&lt;login&gt;.md</code> styles.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/lib/routing.ts"><code>agent/lib/routing.ts</code></a></td><td>Parses the table, matches globs, and unions areas per file.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/lib/prepare-review.ts"><code>agent/lib/prepare-review.ts</code></a></td><td>Fetches PRs or fixtures and builds the evidence tree.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/tools/prepare_review.ts"><code>agent/tools/prepare_review.ts</code></a></td><td>Exposes host preparation as a typed server tool.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/tools/list_review_areas.ts"><code>agent/tools/list_review_areas.ts</code></a></td><td>Answers routing questions deterministically.</td></tr><tr><td><a href="./../../examples/codeowners-review/agent/skills/review-process.html"><code>agent/skills/review-process.md</code></a></td><td>Fixes the fan-out procedure and the verdict rule.</td></tr><tr><td><a href="./../../examples/codeowners-review/agent/subagents/area-reviewer/"><code>agent/subagents/area-reviewer/</code></a></td><td>Defines the one-area, one-playbook reviewer contract.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Reviews opened, reopened, synchronized, and undrafted PRs.</td></tr><tr><td><a href="./../../examples/codeowners-review/fixtures/"><code>fixtures/</code></a></td><td>Ships two reviewable PRs with known planted findings.</td></tr><tr><td><a href="../../examples/codeowners-review/evals/review.eval.ts"><code>evals/review.eval.ts</code></a></td><td>Gates routing, fan-out, planted bugs, and verdicts.</td></tr></tbody></table><p>There is no MCP connection, schedule, hook, A/B experiment, or custom storage.</p><h2 id="prepare-credentials-and-services" tabindex="-1">Prepare credentials and services <a class="header-anchor" href="#prepare-credentials-and-services" aria-label="Permalink to &quot;Prepare credentials and services&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential for model turns.</li><li><code>gh</code> on <code>PATH</code> with read access to real PRs you review. The bundled fixtures need no network at all.</li></ul><p>The channel verifies webhook signatures when <code>GITHUB_WEBHOOK_SECRET</code> is set and narrows repositories with <code>CODEOWNERS_REVIEW_REPOS=owner/repo,owner/other</code>. Pushes re-review in the same session through the <code>pr:&lt;label&gt;</code> continuation token.</p><h2 id="validate-the-surface" tabindex="-1">Validate the surface <a class="header-anchor" href="#validate-the-surface" aria-label="Permalink to &quot;Validate the surface&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/codeowners-review</span></span>
+import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision.","frontmatter":{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision."},"headers":[],"relativePath":"example-agents/codeowners-review.md","filePath":"example-agents/codeowners-review.md"}'),r={name:"example-agents/codeowners-review.md"};function o(n,e,d,l,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="route-pr-reviews-by-code-ownership" tabindex="-1">Route PR reviews by code ownership <a class="header-anchor" href="#route-pr-reviews-by-code-ownership" aria-label="Permalink to &quot;Route PR reviews by code ownership&quot;">​</a></h1><p>Codeowners review gives each part of a codebase its own review. A CODEOWNERS-style table maps changed paths to review areas; each area has a markdown playbook with the team&#39;s rules for that domain; and one <code>area-reviewer</code> subagent runs per routed area, in parallel. A billing change gets the billing review, a migration gets the migration review, and an author&#39;s personal style rides along as advisory notes. The lead aggregates: approve only when every area approves.</p><p>Use this project when review quality depends on domain-specific values instead of one generic checklist.</p><p><a href="./../../examples/codeowners-review/">Browse the codeowners review source.</a></p><h2 id="keep-routing-in-code-and-judgment-in-playbooks" tabindex="-1">Keep routing in code and judgment in playbooks <a class="header-anchor" href="#keep-routing-in-code-and-judgment-in-playbooks" aria-label="Permalink to &quot;Keep routing in code and judgment in playbooks&quot;">​</a></h2><p>The pipeline separates three concerns:</p><ul><li><code>reviews/REVIEWERS</code> routes. Host code matches every changed path against the table; every matching rule applies, and unmatched paths fall back to the <code>general</code> playbook. Routing is glob code with unit tests, not model judgment.</li><li><code>reviews/&lt;area&gt;.md</code> judges. Each playbook is a severity-ordered rule list the team owns: billing mandates integer cents and idempotent webhooks, migrations forbid destructive DDL beside code changes, background jobs demand idempotency and dead-letter paths.</li><li>Subagents review. The lead reads nothing but the manifest and routes; each <code>area-reviewer</code> reads one playbook plus its files&#39; diff hunks and returns a mechanical verdict: request changes on any High finding or two Mediums.</li></ul><p>Personal styles extend the same mechanism. <code>reviews/people/&lt;login&gt;.md</code> attaches automatically, as advisory notes, whenever that person authors the PR. Adding an area or a style is a markdown file plus at most one routing line.</p><h2 id="follow-a-review" tabindex="-1">Follow a review <a class="header-anchor" href="#follow-a-review" aria-label="Permalink to &quot;Follow a review&quot;">​</a></h2><ol><li>A PR arrives: a GitHub <code>pull_request</code> event, a chat message, or a bundled fixture reference.</li><li><code>prepare_review</code> fetches metadata and the diff with the host <code>gh</code> CLI, routes every changed file, and writes the <code>pr/</code> evidence tree: <code>MANIFEST.md</code>, <code>ROUTES.md</code>, <code>diff.patch</code>, and a copy of each matched playbook.</li><li>The lead follows the <code>review-process</code> skill and issues one <code>area-reviewer</code> delegation per routed area, plus one per personal style, all in one step so they run in parallel.</li><li>Each reviewer reads its playbook, reviews only its files, and returns a verdict line with at most three findings.</li><li>The lead aggregates per-area sections and the overall verdict: APPROVE only when every non-advisory area approved.</li></ol><p>Nothing posts to GitHub. Verdicts live in the session; the <a href="./approval-buddy.html">Approval Buddy guide</a> shows how to wire a real APPROVE and commit statuses on top of the same shape.</p><h2 id="map-the-review-files" tabindex="-1">Map the review files <a class="header-anchor" href="#map-the-review-files" aria-label="Permalink to &quot;Map the review files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="./../../examples/codeowners-review/reviews/REVIEWERS.html"><code>reviews/REVIEWERS</code></a></td><td>Routes path patterns to review areas.</td></tr><tr><td><a href="./../../examples/codeowners-review/reviews/"><code>reviews/</code></a></td><td>Holds the area playbooks and <code>people/&lt;login&gt;.md</code> styles.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/lib/routing.ts"><code>agent/lib/routing.ts</code></a></td><td>Parses the table, matches globs, and unions areas per file.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/lib/prepare-review.ts"><code>agent/lib/prepare-review.ts</code></a></td><td>Fetches PRs or fixtures and builds the evidence tree.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/tools/prepare_review.ts"><code>agent/tools/prepare_review.ts</code></a></td><td>Exposes host preparation as a typed server tool.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/tools/list_review_areas.ts"><code>agent/tools/list_review_areas.ts</code></a></td><td>Answers routing questions deterministically.</td></tr><tr><td><a href="./../../examples/codeowners-review/agent/skills/review-process.html"><code>agent/skills/review-process.md</code></a></td><td>Fixes the fan-out procedure and the verdict rule.</td></tr><tr><td><a href="./../../examples/codeowners-review/agent/subagents/area-reviewer/"><code>agent/subagents/area-reviewer/</code></a></td><td>Defines the one-area, one-playbook reviewer contract.</td></tr><tr><td><a href="../../examples/codeowners-review/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Reviews opened, reopened, synchronized, and undrafted PRs.</td></tr><tr><td><a href="./../../examples/codeowners-review/fixtures/"><code>fixtures/</code></a></td><td>Ships two reviewable PRs with known planted findings.</td></tr><tr><td><a href="../../examples/codeowners-review/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/codeowners-review/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/codeowners-review/evals/review.eval.ts"><code>evals/review.eval.ts</code></a></td><td>Gates routing, fan-out, planted bugs, and verdicts.</td></tr></tbody></table><p>There is no MCP connection, schedule, hook, A/B experiment, or custom storage.</p><h2 id="prepare-credentials-and-services" tabindex="-1">Prepare credentials and services <a class="header-anchor" href="#prepare-credentials-and-services" aria-label="Permalink to &quot;Prepare credentials and services&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential for model turns.</li><li><code>gh</code> on <code>PATH</code> with read access to real PRs you review. The bundled fixtures need no network at all.</li></ul><p>The channel verifies webhook signatures when <code>GITHUB_WEBHOOK_SECRET</code> is set and narrows repositories with <code>CODEOWNERS_REVIEW_REPOS=owner/repo,owner/other</code>. Pushes re-review in the same session through the <code>pr:&lt;label&gt;</code> continuation token.</p><h2 id="validate-the-surface" tabindex="-1">Validate the surface <a class="header-anchor" href="#validate-the-surface" aria-label="Permalink to &quot;Validate the surface&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/codeowners-review</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/codeowners-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The manifest should report two server tools, one skill, one subagent, and the authored GitHub channel.</p><h2 id="inspect-routing-without-a-model-turn" tabindex="-1">Inspect routing without a model turn <a class="header-anchor" href="#inspect-routing-without-a-model-turn" aria-label="Permalink to &quot;Inspect routing without a model turn&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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list_review_areas</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/codeowners-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{}&#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;"> prepare_review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

package/dist/docs/assets/{example-agents_codeowners-review.md.D6ay4nvf.lean.js → example-agents_codeowners-review.md.BU2ZXLf-.lean.js}

@@ -1 +1 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision.","frontmatter":{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision."},"headers":[],"relativePath":"example-agents/codeowners-review.md","filePath":"example-agents/codeowners-review.md"}'),r={name:"example-agents/codeowners-review.md"};function o(n,e,l,d,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i("",43)])])}const g=a(r,[["render",o]]);export{u as __pageData,g as default};
+import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision.","frontmatter":{"title":"Route PR reviews by code ownership","description":"Map changed paths to per-area review playbooks, fan one reviewer subagent out per area, and aggregate verdicts into a single approval decision."},"headers":[],"relativePath":"example-agents/codeowners-review.md","filePath":"example-agents/codeowners-review.md"}'),r={name:"example-agents/codeowners-review.md"};function o(n,e,d,l,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i("",43)])])}const g=a(r,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/{example-agents_concierge.md.lL8rhYlj.js → example-agents_concierge.md.DA2al_NK.js}

@@ -1,8 +1,8 @@
-import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions.","frontmatter":{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions."},"headers":[],"relativePath":"example-agents/concierge.md","filePath":"example-agents/concierge.md"}'),n={name:"example-agents/concierge.md"};function l(h,e,o,r,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="compose-agents-with-a-concierge" tabindex="-1">Compose agents with a concierge <a class="header-anchor" href="#compose-agents-with-a-concierge" aria-label="Permalink to &quot;Compose agents with a concierge&quot;">​</a></h1><p>Concierge answers general questions itself and sends every weather question to the weather agent. The connection is one file. The Agent SDK turns the target agent&#39;s MCP endpoint into tools the concierge can call.</p><p>Use this example when two agents are useful on their own and one should delegate a narrow class of work to the other.</p><p><a href="./../../examples/concierge/">Browse the Concierge source.</a></p><h2 id="delegate-through-a-peer-mcp-connection" tabindex="-1">Delegate through a peer MCP connection <a class="header-anchor" href="#delegate-through-a-peer-mcp-connection" aria-label="Permalink to &quot;Delegate through a peer MCP connection&quot;">​</a></h2><p>Concierge has no domain tool of its own. Its capability comes from a peer MCP connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions.","frontmatter":{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions."},"headers":[],"relativePath":"example-agents/concierge.md","filePath":"example-agents/concierge.md"}'),n={name:"example-agents/concierge.md"};function l(o,e,h,r,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="compose-agents-with-a-concierge" tabindex="-1">Compose agents with a concierge <a class="header-anchor" href="#compose-agents-with-a-concierge" aria-label="Permalink to &quot;Compose agents with a concierge&quot;">​</a></h1><p>Concierge answers general questions itself and sends every weather question to the weather agent. The connection is one file. The Agent SDK turns the target agent&#39;s MCP endpoint into tools the concierge can call.</p><p>Use this example when two agents are useful on their own and one should delegate a narrow class of work to the other.</p><p><a href="./../../examples/concierge/">Browse the Concierge source.</a></p><h2 id="delegate-through-a-peer-mcp-connection" tabindex="-1">Delegate through a peer MCP connection <a class="header-anchor" href="#delegate-through-a-peer-mcp-connection" aria-label="Permalink to &quot;Delegate through a peer MCP connection&quot;">​</a></h2><p>Concierge has no domain tool of its own. Its capability comes from a peer MCP connection:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  agent: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;weather-agent&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description:</span></span>
 <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;The weather-agent peer: delegate weather questions with ask; it runs its own tools (live Open-Meteo data) in its own context.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The filename <a href="../../examples/concierge/agent/mcp-connections/weather.ts"><code>weather.ts</code></a> makes the MCP server name <code>weather</code>. The <code>agent</code> field points to the sibling project&#39;s mount slug.</p><p>This differs from a subagent. A peer keeps its own:</p><ul><li>root instructions,</li><li>tools and MCP connections,</li><li>durable sessions,</li><li>playground, and</li><li>public MCP endpoint.</li></ul><p>An SDK subagent inherits the parent&#39;s execution surface and only its parent can invoke it. See <a href="./../guides/agent-to-agent.html">Agent-to-agent</a> for the full comparison.</p><h2 id="follow-a-delegated-request" tabindex="-1">Follow a delegated request <a class="header-anchor" href="#follow-a-delegated-request" aria-label="Permalink to &quot;Follow a delegated request&quot;">​</a></h2><ol><li>A user asks Concierge what to pack for Paris.</li><li><a href="./../../examples/concierge/agent/instructions.html"><code>instructions.md</code></a> classifies packing advice as weather-related.</li><li>The model calls <code>weather.ask</code> with the city, timeframe, units, and the complete question.</li><li>The Agent SDK creates an MCP-channel session inside <code>weather-agent</code>.</li><li>Weather agent calls its own Open-Meteo tools and returns a reply.</li><li>If the turn exceeds the bounded MCP wait, <code>ask</code> returns <code>status: &quot;running&quot;</code>. Concierge calls <code>weather.check</code> with the returned <code>sessionId</code>.</li><li>Concierge relays the result and may add one sentence of travel advice.</li></ol><p>The weather session appears in the weather agent&#39;s playground. It doesn&#39;t share Concierge&#39;s conversation history.</p><h2 id="map-the-delegation-files" tabindex="-1">Map the delegation files <a class="header-anchor" href="#map-the-delegation-files" aria-label="Permalink to &quot;Map the delegation files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/concierge/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Describes the root agent and selects the local runtime.</td></tr><tr><td><a href="./../../examples/concierge/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Draws a strict weather-only delegation boundary.</td></tr><tr><td><a href="../../examples/concierge/agent/mcp-connections/weather.ts"><code>agent/mcp-connections/weather.ts</code></a></td><td>Resolves the peer by its <code>weather-agent</code> slug.</td></tr></tbody></table><p>Concierge doesn&#39;t author channels, tools, skills, subagents, schedules, hooks, A/B experiments, or evals. The built-in HTTP and MCP surfaces still exist.</p><p>Its own MCP endpoint exposes <code>ask</code> and <code>check</code>. It doesn&#39;t expose <code>call_tool</code> because Concierge has no server tools. The target weather agent does expose <code>call_tool</code>, so that tool also appears under Concierge&#39;s <code>weather</code> connection.</p><h2 id="mount-both-agents" tabindex="-1">Mount both agents <a class="header-anchor" href="#mount-both-agents" aria-label="Permalink to &quot;Mount both agents&quot;">​</a></h2><p>A peer can only resolve within a multi-agent serve host. Validating Concierge alone checks its files, but serving it alone fails because <code>weather-agent</code> isn&#39;t mounted.</p><p>From <code>packages/agent-serve</code>, validate both projects:</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/concierge</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The filename <a href="../../examples/concierge/agent/mcp-connections/weather.ts"><code>weather.ts</code></a> makes the MCP server name <code>weather</code>. The <code>agent</code> field points to the sibling project&#39;s mount slug.</p><p>This differs from a subagent. A peer keeps its own:</p><ul><li>root instructions,</li><li>tools and MCP connections,</li><li>durable sessions,</li><li>playground, and</li><li>public MCP endpoint.</li></ul><p>An SDK subagent inherits the parent&#39;s execution surface and only its parent can invoke it. See <a href="./../guides/agent-to-agent.html">Agent-to-agent</a> for the full comparison.</p><h2 id="follow-a-delegated-request" tabindex="-1">Follow a delegated request <a class="header-anchor" href="#follow-a-delegated-request" aria-label="Permalink to &quot;Follow a delegated request&quot;">​</a></h2><ol><li>A user asks Concierge what to pack for Paris.</li><li><a href="./../../examples/concierge/agent/instructions.html"><code>instructions.md</code></a> classifies packing advice as weather-related.</li><li>The model calls <code>weather.ask</code> with the city, timeframe, units, and the complete question.</li><li>The Agent SDK creates an MCP-channel session inside <code>weather-agent</code>.</li><li>Weather agent calls its own Open-Meteo tools and returns a reply.</li><li>If the turn exceeds the bounded MCP wait, <code>ask</code> returns <code>status: &quot;running&quot;</code>. Concierge calls <code>weather.check</code> with the returned <code>sessionId</code>.</li><li>Concierge relays the result and may add one sentence of travel advice.</li></ol><p>The weather session appears in the weather agent&#39;s playground. It doesn&#39;t share Concierge&#39;s conversation history.</p><h2 id="map-the-delegation-files" tabindex="-1">Map the delegation files <a class="header-anchor" href="#map-the-delegation-files" aria-label="Permalink to &quot;Map the delegation files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/concierge/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Describes the root agent and selects the local runtime.</td></tr><tr><td><a href="./../../examples/concierge/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Draws a strict weather-only delegation boundary.</td></tr><tr><td><a href="../../examples/concierge/agent/mcp-connections/weather.ts"><code>agent/mcp-connections/weather.ts</code></a></td><td>Resolves the peer by its <code>weather-agent</code> slug.</td></tr><tr><td><a href="../../examples/concierge/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persists sessions and events with <code>cursorHostedStorage</code>.</td></tr></tbody></table><p>Concierge doesn&#39;t author channels, tools, skills, subagents, schedules, hooks, A/B experiments, or evals. The built-in HTTP and MCP surfaces still exist.</p><p>Its own MCP endpoint exposes <code>ask</code> and <code>check</code>. It doesn&#39;t expose <code>call_tool</code> because Concierge has no server tools. The target weather agent does expose <code>call_tool</code>, so that tool also appears under Concierge&#39;s <code>weather</code> connection.</p><h2 id="mount-both-agents" tabindex="-1">Mount both agents <a class="header-anchor" href="#mount-both-agents" aria-label="Permalink to &quot;Mount both agents&quot;">​</a></h2><p>A peer can only resolve within a multi-agent serve host. Validating Concierge alone checks its files, but serving it alone fails because <code>weather-agent</code> isn&#39;t mounted.</p><p>From <code>packages/agent-serve</code>, validate both projects:</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/concierge</span></span>
 <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></code></pre></div><p>Don&#39;t serve the repository&#39;s whole <code>examples/</code> directory for this proof. Several advanced examples subscribe to live GitHub events. Create an ignored two-project mount instead. Copy only the authored files needed for this proof, leaving Weather&#39;s Slack channels out:</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;">mkdir</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/.agent-serve&quot;</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">PAIR_DIR</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mktemp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/.agent-serve/concierge-weather.XXXXXX&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mkdir</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAIR_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/concierge&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAIR_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/weather-agent/agent&quot;</span></span>

package/dist/docs/assets/{example-agents_concierge.md.lL8rhYlj.lean.js → example-agents_concierge.md.DA2al_NK.lean.js}

@@ -1 +1 @@
-import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions.","frontmatter":{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions."},"headers":[],"relativePath":"example-agents/concierge.md","filePath":"example-agents/concierge.md"}'),n={name:"example-agents/concierge.md"};function l(h,e,o,r,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",52)])])}const g=s(n,[["render",l]]);export{k as __pageData,g as default};
+import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions.","frontmatter":{"title":"Compose agents with a concierge","description":"Delegate weather requests through a peer MCP connection while each agent keeps its own instructions, tools, context, and sessions."},"headers":[],"relativePath":"example-agents/concierge.md","filePath":"example-agents/concierge.md"}'),n={name:"example-agents/concierge.md"};function l(o,e,h,r,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t("",52)])])}const g=s(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/{example-agents_fsd.md.DfNKQTHz.js → example-agents_fsd.md.DPz9ezO4.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Hand PR triage to managed remote agents","description":"Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders.","frontmatter":{"title":"Hand PR triage to managed remote agents","description":"Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders."},"headers":[],"relativePath":"example-agents/fsd.md","filePath":"example-agents/fsd.md"}'),o={name:"example-agents/fsd.md"};function n(r,e,l,d,h,c){return a(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="hand-pr-triage-to-managed-remote-agents" tabindex="-1">Hand PR triage to managed remote agents <a class="header-anchor" href="#hand-pr-triage-to-managed-remote-agents" aria-label="Permalink to &quot;Hand PR triage to managed remote agents&quot;">​</a></h1><p>The remote PR coordinator keeps chat and routing on the local serve host, then hands each pull request to a managed remote agent with a real checkout. The same remote conversation resumes when a user drives the PR again, GitHub reports a change, or a merge-conflict reminder fires.</p><p>The workflow backend enrolls each remote run with a workflow MCP. Its tools and the host&#39;s findings routes read and write the same external findings service.</p><p>Use this example when repository work is too heavy or concurrent for local worktrees, but the host should still own intake, session identity, policy, and bookkeeping.</p><p><a href="./../../examples/fsd/">Browse the current coordinator source.</a></p><h2 id="resume-one-remote-agent-across-every-pr-wake" tabindex="-1">Resume one remote agent across every PR wake <a class="header-anchor" href="#resume-one-remote-agent-across-every-pr-wake" aria-label="Permalink to &quot;Resume one remote agent across every PR wake&quot;">​</a></h2><p>The coordinator uses a hybrid runtime:</p><ul><li>Ordinary playground and Slack chat run locally.</li><li>The <code>drive_pr</code> server tool creates a remote session for one PR.</li><li>The remote worker gets the repository and PR reference.</li><li>An <code>agent.bound</code> hook records the remote run id and enrolls the run into a workflow MCP.</li><li>Webhooks and reminders resume the same remote agent through durable PR-to-agent affinity.</li></ul><p>No other example moves one logical conversation across local chat, remote execution, event wakes, and timed follow-ups.</p><h2 id="follow-a-chat-request" tabindex="-1">Follow a chat request <a class="header-anchor" href="#follow-a-chat-request" aria-label="Permalink to &quot;Follow a chat request&quot;">​</a></h2><ol><li>A user asks local chat or Slack to drive a PR.</li><li>The root model calls <code>drive_pr</code> with the PR, mode, and optional hint.</li><li>The tool calls <code>ctx.send(&quot;drive&quot;, ...)</code> with a per-session <code>cloud</code> block to attach the PR.</li><li>The Agent SDK creates or resumes the <code>drive</code> session keyed by <code>pr:owner/repo#N</code>.</li><li>The remote runtime provisions the agent and emits <code>agent.bound</code>.</li><li>The enrollment hook writes PR affinity and calls the workflow backend to attach run-scoped MCP tools.</li><li><code>drive_pr</code> waits for remote binding, then returns the agent id and URL. If binding exceeds its wait window, those fields can be <code>null</code> while work continues.</li><li>The remote agent reads the host-prepared PR brief, checks unresolved state, and records findings through the workflow MCP.</li><li>The host forwards a validated fallback output block when MCP wasn&#39;t available for the turn.</li></ol><p>The local chat agent doesn&#39;t have the target checkout, <code>gh</code>, <code>git</code>, or the workflow MCP. Its job is coordination.</p><p>A request for a merged or closed PR finishes before provisioning. That result has <code>status: &quot;finished&quot;</code> and no remote session.</p><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>Hybrid config</td><td><a href="../../examples/fsd/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces.</td></tr><tr><td>Root instructions</td><td><a href="./../../examples/fsd/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Separate local coordination from remote triage and define suggest/apply policy.</td></tr><tr><td>Drive tool</td><td><a href="../../examples/fsd/agent/tools/drive_pr.ts"><code>agent/tools/drive_pr.ts</code></a></td><td>Hand a chat request to the <code>drive</code> channel and wait for remote binding.</td></tr><tr><td>Drive channel</td><td><a href="../../examples/fsd/agent/channels/drive.ts"><code>agent/channels/drive.ts</code></a></td><td>Start remote work and expose findings read/write routes.</td></tr><tr><td>GitHub channel</td><td><a href="../../examples/fsd/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Buffer PR, comment, review, check, and status wakes.</td></tr><tr><td>Slack channel</td><td><a href="../../examples/fsd/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Route Slack requests to the local coordinator.</td></tr><tr><td>Hooks</td><td><a href="../../examples/fsd/agent/hooks/enroll-fsd.ts"><code>agent/hooks/enroll-fsd.ts</code></a>, <a href="../../examples/fsd/agent/hooks/record-outputs.ts"><code>agent/hooks/record-outputs.ts</code></a></td><td>Bind remote identity, enroll MCP, and forward fallback findings.</td></tr><tr><td>Affinity and buffering</td><td><a href="../../examples/fsd/agent/lib/pr-affinity.ts"><code>agent/lib/pr-affinity.ts</code></a>, <a href="../../examples/fsd/agent/lib/webhook-buffer.ts"><code>agent/lib/webhook-buffer.ts</code></a></td><td>Persist PR identity, sticky mode, and pending wakes.</td></tr><tr><td>Reminders</td><td><a href="../../examples/fsd/agent/lib/merge-conflict-watch.ts"><code>agent/lib/merge-conflict-watch.ts</code></a></td><td>Recheck merge conflicts every 30 minutes.</td></tr><tr><td>Workflow client</td><td><a href="../../examples/fsd/agent/lib/fsd-platform.ts"><code>agent/lib/fsd-platform.ts</code></a></td><td>Enroll external runs and read or record findings.</td></tr></tbody></table><p>The coordinator has no authored skill, subagent, MCP connection, static schedule, A/B experiment, eval, custom storage definition, or tool approval.</p><p>The workflow MCP is dynamic. Backend enrollment attaches it to the remote run, so there is no file under <code>agent/mcp-connections/</code>.</p><h2 id="understand-local-and-remote-workspaces" tabindex="-1">Understand local and remote workspaces <a class="header-anchor" href="#understand-local-and-remote-workspaces" aria-label="Permalink to &quot;Understand local and remote workspaces&quot;">​</a></h2><p>The root config sets <code>runtime: &quot;local&quot;</code> because <code>drive_pr</code> is a server tool. It also supplies remote-runtime defaults through the <code>cloud</code> configuration:</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;">local</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
+import{_ as t,c as s,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const u=JSON.parse('{"title":"Hand PR triage to managed remote agents","description":"Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders.","frontmatter":{"title":"Hand PR triage to managed remote agents","description":"Coordinate local chat, per-PR remote sessions, GitHub wake buffering, workflow MCP enrollment, durable affinity, findings, and reminders."},"headers":[],"relativePath":"example-agents/fsd.md","filePath":"example-agents/fsd.md"}'),o={name:"example-agents/fsd.md"};function n(r,e,l,d,h,c){return a(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="hand-pr-triage-to-managed-remote-agents" tabindex="-1">Hand PR triage to managed remote agents <a class="header-anchor" href="#hand-pr-triage-to-managed-remote-agents" aria-label="Permalink to &quot;Hand PR triage to managed remote agents&quot;">​</a></h1><p>The remote PR coordinator keeps chat and routing on the local serve host, then hands each pull request to a managed remote agent with a real checkout. The same remote conversation resumes when a user drives the PR again, GitHub reports a change, or a merge-conflict reminder fires.</p><p>The workflow backend enrolls each remote run with a workflow MCP. Its tools and the host&#39;s findings routes read and write the same external findings service.</p><p>Use this example when repository work is too heavy or concurrent for local worktrees, but the host should still own intake, session identity, policy, and bookkeeping.</p><p><a href="./../../examples/fsd/">Browse the current coordinator source.</a></p><h2 id="resume-one-remote-agent-across-every-pr-wake" tabindex="-1">Resume one remote agent across every PR wake <a class="header-anchor" href="#resume-one-remote-agent-across-every-pr-wake" aria-label="Permalink to &quot;Resume one remote agent across every PR wake&quot;">​</a></h2><p>The coordinator uses a hybrid runtime:</p><ul><li>Ordinary playground and Slack chat run locally.</li><li>The <code>drive_pr</code> server tool creates a remote session for one PR.</li><li>The remote worker gets the repository and PR reference.</li><li>An <code>agent.bound</code> hook records the remote run id and enrolls the run into a workflow MCP.</li><li>Webhooks and reminders resume the same remote agent through durable PR-to-agent affinity.</li></ul><p>No other example moves one logical conversation across local chat, remote execution, event wakes, and timed follow-ups.</p><h2 id="follow-a-chat-request" tabindex="-1">Follow a chat request <a class="header-anchor" href="#follow-a-chat-request" aria-label="Permalink to &quot;Follow a chat request&quot;">​</a></h2><ol><li>A user asks local chat or Slack to drive a PR.</li><li>The root model calls <code>drive_pr</code> with the PR, mode, and optional hint.</li><li>The tool calls <code>ctx.send(&quot;drive&quot;, ...)</code> with a per-session <code>cloud</code> block to attach the PR.</li><li>The Agent SDK creates or resumes the <code>drive</code> session keyed by <code>pr:owner/repo#N</code>.</li><li>The remote runtime provisions the agent and emits <code>agent.bound</code>.</li><li>The enrollment hook writes PR affinity and calls the workflow backend to attach run-scoped MCP tools.</li><li><code>drive_pr</code> waits for remote binding, then returns the agent id and URL. If binding exceeds its wait window, those fields can be <code>null</code> while work continues.</li><li>The remote agent reads the host-prepared PR brief, checks unresolved state, and records findings through the workflow MCP.</li><li>The host forwards a validated fallback output block when MCP wasn&#39;t available for the turn.</li></ol><p>The local chat agent doesn&#39;t have the target checkout, <code>gh</code>, <code>git</code>, or the workflow MCP. Its job is coordination.</p><p>A request for a merged or closed PR finishes before provisioning. That result has <code>status: &quot;finished&quot;</code> and no remote session.</p><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>Hybrid config</td><td><a href="../../examples/fsd/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Keep chat local, set remote-runtime defaults, disable automatic PR creation, and isolate local harness workspaces.</td></tr><tr><td>Root instructions</td><td><a href="./../../examples/fsd/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Separate local coordination from remote triage and define suggest/apply policy.</td></tr><tr><td>Drive tool</td><td><a href="../../examples/fsd/agent/tools/drive_pr.ts"><code>agent/tools/drive_pr.ts</code></a></td><td>Hand a chat request to the <code>drive</code> channel and wait for remote binding.</td></tr><tr><td>Drive channel</td><td><a href="../../examples/fsd/agent/channels/drive.ts"><code>agent/channels/drive.ts</code></a></td><td>Start remote work and expose findings read/write routes.</td></tr><tr><td>GitHub channel</td><td><a href="../../examples/fsd/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Buffer PR, comment, review, check, and status wakes.</td></tr><tr><td>Slack channel</td><td><a href="../../examples/fsd/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Route Slack requests to the local coordinator.</td></tr><tr><td>Hooks</td><td><a href="../../examples/fsd/agent/hooks/enroll-fsd.ts"><code>agent/hooks/enroll-fsd.ts</code></a>, <a href="../../examples/fsd/agent/hooks/record-outputs.ts"><code>agent/hooks/record-outputs.ts</code></a></td><td>Bind remote identity, enroll MCP, and forward fallback findings.</td></tr><tr><td>Affinity and buffering</td><td><a href="../../examples/fsd/agent/lib/pr-affinity.ts"><code>agent/lib/pr-affinity.ts</code></a>, <a href="../../examples/fsd/agent/lib/webhook-buffer.ts"><code>agent/lib/webhook-buffer.ts</code></a></td><td>Persist PR identity, sticky mode, and pending wakes.</td></tr><tr><td>Reminders</td><td><a href="../../examples/fsd/agent/lib/merge-conflict-watch.ts"><code>agent/lib/merge-conflict-watch.ts</code></a></td><td>Recheck merge conflicts every 30 minutes.</td></tr><tr><td>Workflow client</td><td><a href="../../examples/fsd/agent/lib/fsd-platform.ts"><code>agent/lib/fsd-platform.ts</code></a></td><td>Enroll external runs and read or record findings.</td></tr><tr><td>Storage</td><td><a href="../../examples/fsd/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persist sessions and events with <code>cursorHostedStorage</code>.</td></tr></tbody></table><p>The coordinator has no authored skill, subagent, MCP connection, static schedule, A/B experiment, eval, custom storage definition, or tool approval.</p><p>The workflow MCP is dynamic. Backend enrollment attaches it to the remote run, so there is no file under <code>agent/mcp-connections/</code>.</p><h2 id="understand-local-and-remote-workspaces" tabindex="-1">Understand local and remote workspaces <a class="header-anchor" href="#understand-local-and-remote-workspaces" aria-label="Permalink to &quot;Understand local and remote workspaces&quot;">​</a></h2><p>The root config sets <code>runtime: &quot;local&quot;</code> because <code>drive_pr</code> is a server tool. It also supplies remote-runtime defaults through the <code>cloud</code> configuration:</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;">local</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  cwd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">homedir</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;.cache&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agent-serve&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fsd&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cloud</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>

package/dist/docs/assets/{example-agents_knowledge-base.md.CzyZ2DCr.js → example-agents_knowledge-base.md.IneynQSR.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.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(`<h1 id="build-a-team-knowledge-base-through-conversation" tabindex="-1">Build a team knowledge base through conversation <a class="header-anchor" href="#build-a-team-knowledge-base-through-conversation" aria-label="Permalink to &quot;Build a team knowledge base through conversation&quot;">​</a></h1><p>Knowledge base turns conversations into shared team context. Teach the agent about people, systems, decisions, and standing preferences. Three server tools read, search, and write human-readable markdown pages; a conventions skill shapes each write; and a daily schedule merges duplicates and rebuilds the index. A fresh session retrieves what an earlier conversation captured.</p><p>Use this project when people should curate organizational knowledge through chat. Use <a href="./codebase-wiki.html">Codebase wiki</a> when merged PRs should maintain feature documentation instead.</p><p><a href="./../../examples/knowledge-base/">Browse the knowledge base source.</a></p><h2 id="keep-shared-knowledge-on-the-filesystem" tabindex="-1">Keep shared knowledge on the filesystem <a class="header-anchor" href="#keep-shared-knowledge-on-the-filesystem" aria-label="Permalink to &quot;Keep shared knowledge on the filesystem&quot;">​</a></h2><p>The knowledge base lives outside any session workspace, in <code>.agent-serve/wiki/</code> by default. <code>KNOWLEDGE_BASE_DIR</code> overrides the location, and the tools resolve it on every call, so tests and evals can point the same code at a temp directory.</p><p>The store enforces its own safety:</p><ul><li>Page ids are one to three lowercase kebab-case segments, so a page id can&#39;t escape the wiki directory.</li><li>Pages cap at 64 KiB. Oversized writes fail with instructions to split the page.</li><li><code>wiki_write</code> replaces whole pages. The instructions require reading a page before updating it, so rewrites carry existing facts forward.</li></ul><p>Every page is plain markdown. You can open the wiki in an editor, review it in a PR, or grep it.</p><h2 id="follow-a-fact-through-the-agent" tabindex="-1">Follow a fact through the agent <a class="header-anchor" href="#follow-a-fact-through-the-agent" aria-label="Permalink to &quot;Follow a fact through the agent&quot;">​</a></h2><ol><li>You tell the agent something durable: a system, an owner, a standing preference.</li><li>The instructions require a <code>wiki_search</code> before claiming knowledge and a <code>wiki_write</code> after learning something worth keeping.</li><li>The <code>wiki-conventions</code> skill picks the page id (<code>staging-database</code>, <code>people/jane-doe</code>), the page shape, and the dated fact format.</li><li>The tool writes the page under the durable wiki root and returns whether it created or updated the page.</li><li>A later session, on any channel, finds the fact with <code>wiki_search</code> and cites the knowledge-base page in its answer.</li></ol><p>Ephemeral chatter stays out. The instructions tell the model to skip one-off questions and to ask before saving anything borderline.</p><h2 id="map-the-knowledge-base-files" tabindex="-1">Map the knowledge-base files <a class="header-anchor" href="#map-the-knowledge-base-files" aria-label="Permalink to &quot;Map the knowledge-base files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/knowledge-base/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Selects the cloud runtime and model.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Sets the read-before-answer and save-after-learning policy.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/lib/wiki-store.ts"><code>agent/lib/wiki-store.ts</code></a></td><td>Validates page ids, lists, reads, writes, and searches the knowledge base.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_read.ts"><code>agent/tools/wiki_read.ts</code></a></td><td>Reads one page or lists every page with titles and timestamps.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_search.ts"><code>agent/tools/wiki_search.ts</code></a></td><td>Searches titles and bodies with per-page match lines.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_write.ts"><code>agent/tools/wiki_write.ts</code></a></td><td>Creates or replaces a page and reports created versus updated.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/skills/wiki-conventions.html"><code>agent/skills/wiki-conventions.md</code></a></td><td>Names pages, shapes them, and dates every fact.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/schedules/gardener.html"><code>agent/schedules/gardener.md</code></a></td><td>Merges duplicates, rebuilds the index, and flags stale facts daily.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/lib/wiki-store.test.ts"><code>agent/lib/wiki-store.test.ts</code></a></td><td>Unit-tests slug safety and store round-trips.</td></tr><tr><td><a href="../../examples/knowledge-base/evals/knowledge.eval.ts"><code>evals/knowledge.eval.ts</code></a></td><td>Seeds a temp knowledge base and gates recall, save, and no-write decisions.</td></tr></tbody></table><p>There is no authored channel, MCP connection, subagent, hook, A/B experiment, or custom storage. The wiki directory is the durable state.</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 for model turns.</li></ul><p>Nothing else. The wiki is created on first write.</p><h2 id="validate-the-surface" tabindex="-1">Validate the surface <a class="header-anchor" href="#validate-the-surface" aria-label="Permalink to &quot;Validate the surface&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/knowledge-base</span></span>
+import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.CAZyNGu9.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(`<h1 id="build-a-team-knowledge-base-through-conversation" tabindex="-1">Build a team knowledge base through conversation <a class="header-anchor" href="#build-a-team-knowledge-base-through-conversation" aria-label="Permalink to &quot;Build a team knowledge base through conversation&quot;">​</a></h1><p>Knowledge base turns conversations into shared team context. Teach the agent about people, systems, decisions, and standing preferences. Three server tools read, search, and write human-readable markdown pages; a conventions skill shapes each write; and a daily schedule merges duplicates and rebuilds the index. A fresh session retrieves what an earlier conversation captured.</p><p>Use this project when people should curate organizational knowledge through chat. Use <a href="./codebase-wiki.html">Codebase wiki</a> when merged PRs should maintain feature documentation instead.</p><p><a href="./../../examples/knowledge-base/">Browse the knowledge base source.</a></p><h2 id="keep-shared-knowledge-on-the-filesystem" tabindex="-1">Keep shared knowledge on the filesystem <a class="header-anchor" href="#keep-shared-knowledge-on-the-filesystem" aria-label="Permalink to &quot;Keep shared knowledge on the filesystem&quot;">​</a></h2><p>The knowledge base lives outside any session workspace, in <code>.agent-serve/wiki/</code> by default. <code>KNOWLEDGE_BASE_DIR</code> overrides the location, and the tools resolve it on every call, so tests and evals can point the same code at a temp directory.</p><p>The store enforces its own safety:</p><ul><li>Page ids are one to three lowercase kebab-case segments, so a page id can&#39;t escape the wiki directory.</li><li>Pages cap at 64 KiB. Oversized writes fail with instructions to split the page.</li><li><code>wiki_write</code> replaces whole pages. The instructions require reading a page before updating it, so rewrites carry existing facts forward.</li></ul><p>Every page is plain markdown. You can open the wiki in an editor, review it in a PR, or grep it.</p><h2 id="follow-a-fact-through-the-agent" tabindex="-1">Follow a fact through the agent <a class="header-anchor" href="#follow-a-fact-through-the-agent" aria-label="Permalink to &quot;Follow a fact through the agent&quot;">​</a></h2><ol><li>You tell the agent something durable: a system, an owner, a standing preference.</li><li>The instructions require a <code>wiki_search</code> before claiming knowledge and a <code>wiki_write</code> after learning something worth keeping.</li><li>The <code>wiki-conventions</code> skill picks the page id (<code>staging-database</code>, <code>people/jane-doe</code>), the page shape, and the dated fact format.</li><li>The tool writes the page under the durable wiki root and returns whether it created or updated the page.</li><li>A later session, on any channel, finds the fact with <code>wiki_search</code> and cites the knowledge-base page in its answer.</li></ol><p>Ephemeral chatter stays out. The instructions tell the model to skip one-off questions and to ask before saving anything borderline.</p><h2 id="map-the-knowledge-base-files" tabindex="-1">Map the knowledge-base files <a class="header-anchor" href="#map-the-knowledge-base-files" aria-label="Permalink to &quot;Map the knowledge-base files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/knowledge-base/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Selects the cloud runtime and model.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Sets the read-before-answer and save-after-learning policy.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/lib/wiki-store.ts"><code>agent/lib/wiki-store.ts</code></a></td><td>Validates page ids, lists, reads, writes, and searches the knowledge base.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_read.ts"><code>agent/tools/wiki_read.ts</code></a></td><td>Reads one page or lists every page with titles and timestamps.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_search.ts"><code>agent/tools/wiki_search.ts</code></a></td><td>Searches titles and bodies with per-page match lines.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/tools/wiki_write.ts"><code>agent/tools/wiki_write.ts</code></a></td><td>Creates or replaces a page and reports created versus updated.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/skills/wiki-conventions.html"><code>agent/skills/wiki-conventions.md</code></a></td><td>Names pages, shapes them, and dates every fact.</td></tr><tr><td><a href="./../../examples/knowledge-base/agent/schedules/gardener.html"><code>agent/schedules/gardener.md</code></a></td><td>Merges duplicates, rebuilds the index, and flags stale facts daily.</td></tr><tr><td><a href="../../examples/knowledge-base/agent/lib/wiki-store.test.ts"><code>agent/lib/wiki-store.test.ts</code></a></td><td>Unit-tests slug safety and store round-trips.</td></tr><tr><td><a href="../../examples/knowledge-base/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/knowledge-base/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/knowledge-base/evals/knowledge.eval.ts"><code>evals/knowledge.eval.ts</code></a></td><td>Seeds a temp knowledge base and gates recall, save, and no-write decisions.</td></tr></tbody></table><p>There is no authored channel, MCP connection, subagent, hook, A/B experiment, or custom storage. The wiki directory is the durable state.</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 for model turns.</li></ul><p>Nothing else. The wiki is created on first write.</p><h2 id="validate-the-surface" tabindex="-1">Validate the surface <a class="header-anchor" href="#validate-the-surface" aria-label="Permalink to &quot;Validate the surface&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/knowledge-base</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/knowledge-base</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The manifest should report three server tools, one skill, and one schedule.</p><h2 id="exercise-the-store-without-a-model-turn" tabindex="-1">Exercise the store without a model turn <a class="header-anchor" href="#exercise-the-store-without-a-model-turn" aria-label="Permalink to &quot;Exercise the store without a model turn&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;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> wiki_write</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/knowledge-base</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;page&quot;:&quot;staging-database&quot;,&quot;content&quot;:&quot;# Staging database\\n\\n- Port: 6432 (recorded 2026-07-19)\\n&quot;}&#39;</span></span>

package/dist/docs/assets/{example-agents_oncall.md.wFFXXEyW.js → example-agents_oncall.md.ZE0n6ZFN.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.CAZyNGu9.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/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>
+import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.CAZyNGu9.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>

package/dist/docs/assets/{example-agents_slack-agent.md.DvgvT4nn.js → example-agents_slack-agent.md.06jQXTAI.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.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></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>
+import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.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>

package/dist/docs/assets/{example-agents_weather-agent.md.BADkPqxQ.js → example-agents_weather-agent.md.CrGZ0SqR.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, 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 server tools, MCP, channels, approvals, 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,p,d){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 pauses an alert tool for human approval. The same agent also 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 architecture. 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>Execute on the Agent SDK host through authenticated HTTP MCP, fetch Open-Meteo data, call MCP, and model an approval-gated action.</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></td><td>Expose conversion tools to the model, host tools, and channel handlers.</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 offering approval buttons.</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 hook</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></td><td>Start recurring task sessions and observe completed turns.</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 approval-enabled 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>
+import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, 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 server tools, MCP, channels, approvals, 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 o(h,e,l,r,p,d){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 pauses an alert tool for human approval. The same agent also 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 architecture. 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>Execute on the Agent SDK host through authenticated HTTP MCP, fetch Open-Meteo data, call MCP, and model an approval-gated action.</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></td><td>Expose conversion tools to the model, host tools, and channel handlers.</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 offering approval buttons.</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 hook</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></td><td>Start recurring task sessions and observe completed turns.</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 approval-enabled 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>
@@ -7,7 +7,7 @@ import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k
 <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 execute on the Agent SDK host through an authenticated HTTP MCP endpoint while retaining the active session context. For an agent tool, the Agent SDK includes its catalog and script body in the first prompt; the cloud model writes and invokes the script in its VM.</p><h2 id="verify-cloud-custom-tool-execution" tabindex="-1">Verify cloud custom-tool execution <a class="header-anchor" href="#verify-cloud-custom-tool-execution" aria-label="Permalink to &quot;Verify cloud custom-tool execution&quot;">​</a></h2><p>Ask the agent to run <code>probe_cloud_tool</code>. It writes a deployment-scoped marker and returns the complete session id, tool-call id, and marker path. Correlate those ids with <code>actions.requested</code> / <code>action.result</code> in the session stream and the host&#39;s <code>cloud HTTP MCP tool ... dispatch/complete</code> log lines.</p><p>For a body-only smoke test:</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;"> probe_cloud_tool</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 execute on the Agent SDK host through an authenticated HTTP MCP endpoint while retaining the active session context. For an agent tool, the Agent SDK includes its catalog and script body in the first prompt; the cloud model writes and invokes the script in its VM.</p><h2 id="verify-cloud-custom-tool-execution" tabindex="-1">Verify cloud custom-tool execution <a class="header-anchor" href="#verify-cloud-custom-tool-execution" aria-label="Permalink to &quot;Verify cloud custom-tool execution&quot;">​</a></h2><p>Ask the agent to run <code>probe_cloud_tool</code>. On cloud that tool is MCP on <code>agentsdk-tools</code>, not a local script. A real call writes a deployment-scoped marker at <code>tool-observations/&lt;sessionId&gt;/&lt;toolCallId&gt;.json</code> and returns those ids. Correlate them with <code>actions.requested</code> / <code>action.result</code> for <code>probe_cloud_tool</code> (not <code>shell</code>) and the host&#39;s <code>cloud HTTP MCP tool ... dispatch/complete</code> log lines.</p><p>A local <code>.agent-serve/tools/probe_cloud_tool.sh</code> or a marker under <code>probes/</code> means the model invented a substitute and the host never ran.</p><p>For a body-only smoke test:</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;"> probe_cloud_tool</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;label&quot;:&quot;weather example smoke test&quot;}&#39;</span></span></code></pre></div><p>That deterministic call verifies the tool body and marker. A normal cloud model turn verifies the full Cloud Agent → HTTP MCP gateway → Agent SDK host path.</p><h2 id="use-one-mcp-connection-in-three-places" tabindex="-1">Use one MCP connection in three places <a class="header-anchor" href="#use-one-mcp-connection-in-three-places" aria-label="Permalink to &quot;Use one MCP connection 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>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>
@@ -23,4 +23,4 @@ import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k
 <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="pause-a-tool-for-human-approval" tabindex="-1">Pause a tool for human approval <a class="header-anchor" href="#pause-a-tool-for-human-approval" aria-label="Permalink to &quot;Pause a tool for human approval&quot;">​</a></h2><p><code>post_weather_alert</code> sets <code>needsApproval: true</code>. Ask for an ops alert in the playground and the model&#39;s tool call parks before <code>execute</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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent</span></span></code></pre></div><p>Open the printed playground URL, ask:</p><blockquote><p>Alert ops that severe weather is approaching Boston.</p></blockquote><p>Approve or deny the call in the transcript. The dedicated Socket Mode Slack channel can show the same buttons when <code>toolApprovals: true</code> and Slack interactivity are configured.</p><p>The example tool returns a placeholder success object. It doesn&#39;t contact Slack, PagerDuty, or an ops board. Replace its <code>execute</code> body with your own sink before adapting it.</p><p>Use a model turn for this proof. A deterministic <code>agent-sdk call</code> runs the tool body directly and doesn&#39;t demonstrate the parked approval flow.</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 <code>.agent-serve/</code>. 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>Six cases cover current weather and forecasts against live Open-Meteo. Two more cover the local MCP converter and workspace note tool. Together they test model routing, external data, host MCP, and agent-side execution.</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 architecture 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>Gate side effects with <code>needsApproval</code>.</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>`,84)])])}const u=s(n,[["render",h]]);export{k as __pageData,u as default};
+<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>Six cases cover current weather and forecasts against live Open-Meteo. Two more cover the local MCP converter and workspace note tool. Together they test model routing, external data, host MCP, and agent-side execution.</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 architecture 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>Gate side effects with <code>needsApproval</code>.</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>`,85)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{example-agents_weather-agent.md.BADkPqxQ.lean.js → example-agents_weather-agent.md.CrGZ0SqR.lean.js}

@@ -1 +1 @@
-import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, 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 server tools, MCP, channels, approvals, 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,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i("",84)])])}const u=s(n,[["render",h]]);export{k as __pageData,u as default};
+import{_ as s,c as a,o as t,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Explore the full Agent SDK surface with a weather agent","description":"Trace cloud server tools, MCP, channels, approvals, 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 server tools, MCP, channels, approvals, 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 o(h,e,l,r,p,d){return t(),a("div",null,[...e[0]||(e[0]=[i("",85)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

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

@@ -0,0 +1,9 @@
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.CAZyNGu9.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 s(),o("div",null,[...e[0]||(e[0]=[a(`<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>only if present in the cloud repo</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>Hosted deployments configure the server-tool MCP URL automatically (<code>cloudToolsUrl</code>, authenticated with the resolved Cursor API key). A self-hosted public server needs <code>--public-url</code> (and <code>--bearer-token</code> when the host is not behind another trusted authentication boundary) so cloud turns can reach those tools. Without either, the server warns at startup and cloud turns omit the server tools.</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>Two more behaviors are cloud-specific. Sessions persist a separate SDK agent id (<code>bc-…</code>), emitted on the stream as <code>agent.bound</code> with a URL to the cloud conversation. Cloud ids are minted during the first send. And peer MCP connections resolve to <code>--public-url</code> for cloud turns, because a VM cannot reach the host&#39;s loopback; without one, peers are omitted from cloud turns 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 agent per unit of work (per PR, say). Store the <code>bc-…</code> id keyed by the work unit (an affinity store written from an <code>agent.bound</code> hook) so webhook wakes resume the same conversation instead of booting a fresh VM per event.</li><li>Stable continuation keys (<code>pr:owner/repo#N</code>) so every wake lands on the same session within a channel.</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 precisely</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.V5igN4Sq.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as o,o as s,ag as a}from"./chunks/framework.CAZyNGu9.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 s(),o("div",null,[...e[0]||(e[0]=[a("",28)])])}const g=t(n,[["render",i]]);export{p as __pageData,g as default};

package/dist/docs/assets/{guides_webhooks.md.DiAwSR42.js → guides_webhooks.md.BERuBSJW.js}

@@ -42,7 +42,7 @@ import{_ as i,c as a,o as n,ag as h}from"./chunks/framework.CAZyNGu9.js";const o
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`pr:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</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:#D73A49;--shiki-dark:#F97583;">  return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ sessionId: session.id });</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>This host-prep shape is the change with the largest effect on latency and quality. <a href="./../hillclimbing.html">Hillclimbing</a> lists it first.</p><h2 id="deliver-replies-back-out" tabindex="-1">Deliver replies back out <a class="header-anchor" href="#deliver-replies-back-out" aria-label="Permalink to &quot;Deliver replies back out&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Typical wiring: <code>message.completed</code> posts the assistant text back to the caller&#39;s surface, and <code>turn.failed</code> posts an error notice. The full vocabulary is in <a href="./../reference/sessions.html#the-event-vocabulary">Sessions and streaming</a>.</p><h2 id="auth-loopback-by-default-on-purpose" tabindex="-1">Auth: loopback by default, on purpose <a class="header-anchor" href="#auth-loopback-by-default-on-purpose" aria-label="Permalink to &quot;Auth: loopback by default, on purpose&quot;">​</a></h2><p>Every route runs an auth-policy chain (the channel&#39;s <code>auth</code> array). The default is <code>[localDevStrict()]</code>: direct loopback callers only. Requests carrying proxy-forwarding headers (<code>X-Forwarded-For</code>, <code>X-Real-IP</code>, <code>Forwarded</code>, <code>X-Forwarded-Host</code>) are rejected, and a loopback <code>Host</code> header is required. So a tunnel, a same-host reverse proxy, or a DNS-rebinding page can&#39;t silently re-expose the route.</p><p>Before real traffic, author auth explicitly:</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;"> { bearerAuth, defineChannel, localDevStrict } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>This host-prep shape is the change with the largest effect on latency and quality. <a href="./../hillclimbing.html">Hillclimbing</a> lists it first.</p><h2 id="deliver-replies-back-out" tabindex="-1">Deliver replies back out <a class="header-anchor" href="#deliver-replies-back-out" aria-label="Permalink to &quot;Deliver replies back out&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Typical wiring: <code>message.completed</code> posts the assistant text back to the caller&#39;s surface, and <code>turn.failed</code> posts an error notice. The full vocabulary is in <a href="./../reference/sessions.html#which-events-can-i-stream">Sessions and streaming</a>.</p><h2 id="auth-loopback-by-default-on-purpose" tabindex="-1">Auth: loopback by default, on purpose <a class="header-anchor" href="#auth-loopback-by-default-on-purpose" aria-label="Permalink to &quot;Auth: loopback by default, on purpose&quot;">​</a></h2><p>Every route runs an auth-policy chain (the channel&#39;s <code>auth</code> array). The default is <code>[localDevStrict()]</code>: direct loopback callers only. Requests carrying proxy-forwarding headers (<code>X-Forwarded-For</code>, <code>X-Real-IP</code>, <code>Forwarded</code>, <code>X-Forwarded-Host</code>) are rejected, and a loopback <code>Host</code> header is required. So a tunnel, a same-host reverse proxy, or a DNS-rebinding page can&#39;t silently re-expose the route.</p><p>Before real traffic, author auth explicitly:</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;"> { bearerAuth, defineChannel, localDevStrict } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&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;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  auth: [</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">localDevStrict</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bearerAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">WEBHOOK_TOKEN</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)],</span></span>