@cursor/july 0.1.93 → 0.1.95

package/dist/docs/assets/concepts.md.F6AiPorA.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o,ag as s}from"./chunks/framework.BCISBCiQ.js";const p=JSON.parse('{"title":"How the Agent SDK works","description":"Understand projects, sessions, event streams, channels, and runtimes in plain language.","frontmatter":{"title":"How the Agent SDK works","description":"Understand projects, sessions, event streams, channels, and runtimes in plain language."},"headers":[],"relativePath":"concepts.md","filePath":"concepts.md"}'),n={name:"concepts.md"};function r(d,e,l,i,c,h){return o(),a("div",null,[...e[0]||(e[0]=[s('<h1 id="how-the-agent-sdk-works" tabindex="-1">How the Agent SDK works <a class="header-anchor" href="#how-the-agent-sdk-works" aria-label="Permalink to &quot;How the Agent SDK works&quot;">​</a></h1><p>An agent is a folder of instructions and capabilities. The Agent SDK discovers those files, runs conversations, and records what happened.</p><h2 id="what-happens-when-someone-sends-a-message" tabindex="-1">What happens when someone sends a message? <a class="header-anchor" href="#what-happens-when-someone-sends-a-message" aria-label="Permalink to &quot;What happens when someone sends a message?&quot;">​</a></h2><p>Follow one message through the system:</p><ol><li>A channel receives the message from HTTP, Slack, GitHub, or another webhook.</li><li>The channel starts a session or continues an existing one.</li><li>The runtime gives the model its instructions, tools, and workspace.</li><li>The model replies and can call tools along the way.</li><li>The Agent SDK appends every message and tool call to the session&#39;s event stream.</li></ol><p>The channel is the front door. The runtime does the work. The event stream is the record you inspect later.</p><h2 id="how-do-files-become-an-agent" tabindex="-1">How do files become an agent? <a class="header-anchor" href="#how-do-files-become-an-agent" aria-label="Permalink to &quot;How do files become an agent?&quot;">​</a></h2><p>Each capability has a home in the project. The path tells the Agent SDK what to load. The filename becomes the capability&#39;s name. For example, <code>agent/tools/get_weather.ts</code> creates a tool named <code>get_weather</code>.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td>Model and runtime settings</td></tr><tr><td><code>agent/instructions.md</code></td><td>The always-on system prompt</td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>Typed actions the model can call</td></tr><tr><td><code>agent/skills/*</code></td><td>Procedures loaded when needed</td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>Tools from external MCP servers</td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP, Slack, and GitHub entry points</td></tr><tr><td><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></td><td>Sticky variants and live performance metrics</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Repeatable checks at the project root</td></tr></tbody></table><p>Other folders add subagents, hooks, schedules, and workspace files. You don&#39;t register them elsewhere. Run <code>agent-sdk validate</code> to catch invalid files before serving the project.</p><p>See <a href="./reference/project-layout.html">Project layout</a> for the folder structure.</p><h2 id="how-does-the-agent-sdk-identify-a-conversation" tabindex="-1">How does the Agent SDK identify a conversation? <a class="header-anchor" href="#how-does-the-agent-sdk-identify-a-conversation" aria-label="Permalink to &quot;How does the Agent SDK identify a conversation?&quot;">​</a></h2><p>A session is one durable conversation. It has two identifiers:</p><ul><li><strong><code>continuationToken</code></strong> tells a channel which conversation to resume. A Slack channel can use its thread ID. A GitHub channel can use the pull request. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up.</li><li><strong><code>sessionId</code></strong> identifies the stored session. Use it to stream events, inspect the session, resolve approvals, or bind a tool call to the session.</li></ul><p>Use the continuation token to keep talking. Use the session ID to observe or manage the conversation.</p><h2 id="how-do-i-see-what-an-agent-did" tabindex="-1">How do I see what an agent did? <a class="header-anchor" href="#how-do-i-see-what-an-agent-did" aria-label="Permalink to &quot;How do I see what an agent did?&quot;">​</a></h2><p>Each session records an append-only event stream. It includes:</p><ul><li>Messages and streamed text</li><li>Requested tool calls and their results</li><li>Approval requests and decisions</li><li>Turn completion and token usage</li></ul><p>Sessions and their event streams survive server restarts. The playground renders the stream. Evals assert against it. The <code>agent-sdk trajectory</code> command turns a saved stream into a short summary.</p><p>When a run surprises you, inspect its event stream first. See <a href="./reference/sessions.html">Sessions and streaming</a> for the event vocabulary.</p><h2 id="what-does-a-channel-control" tabindex="-1">What does a channel control? <a class="header-anchor" href="#what-does-a-channel-control" aria-label="Permalink to &quot;What does a channel control?&quot;">​</a></h2><p>A channel connects the agent to a surface such as HTTP, Slack, GitHub, or a custom webhook. It controls:</p><ul><li>Routes and input schemas</li><li>Authentication</li><li>Conversation identity</li><li>How replies return to the user</li></ul><p>The built-in HTTP session API is always available. Custom routes accept loopback callers by default. Add an auth policy before sharing them over a network.</p><p>Channels should also prepare deterministic input for the model. For example, a GitHub channel can fetch the pull request, collect the diff, and seed the workspace before the turn starts. The model can then focus on the review instead of gathering files.</p><p>See <a href="./reference/channels.html">Channels</a> for route and authentication details.</p><h2 id="where-does-a-turn-run" tabindex="-1">Where does a turn run? <a class="header-anchor" href="#where-does-a-turn-run" aria-label="Permalink to &quot;Where does a turn run?&quot;">​</a></h2><p>Choose a runtime in <code>agent/agent.ts</code>:</p><table tabindex="0"><thead><tr><th></th><th>Local (default)</th><th>Cloud</th></tr></thead><tbody><tr><td>Turn runs on</td><td>The server host</td><td>A Cursor cloud agent</td></tr><tr><td>Server tools</td><td>Supported</td><td>Supported when the server has <code>--public-url</code> or <code>--cloud-tools-url</code>; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them.</td></tr><tr><td>Approvals (<code>needsApproval</code>)</td><td>Supported</td><td>Not supported (local runtime only)</td></tr><tr><td>Agent tool scripts</td><td>Supported</td><td>Supported</td></tr><tr><td>Skills</td><td>Added to the session workspace</td><td>Available automatically</td></tr><tr><td>Seeded files</td><td>Added to the session workspace</td><td>Ignored</td></tr><tr><td>Repository</td><td>You provide it</td><td>The cloud agent checks it out</td></tr></tbody></table><p>Use the local runtime when the host has the tools and files the agent needs. Use the cloud runtime when each turn needs an isolated repository checkout. <code>agent-sdk validate</code> warns when a cloud agent uses a local-only capability.</p><p>See <a href="./guides/cloud-runtime.html">Cloud runtime</a> for setup and trade-offs.</p><h2 id="what-files-can-a-local-session-access" tabindex="-1">What files can a local session access? <a class="header-anchor" href="#what-files-can-a-local-session-access" aria-label="Permalink to &quot;What files can a local session access?&quot;">​</a></h2><p>Each local session gets its own workspace. The Agent SDK writes the instructions as <code>AGENTS.md</code>, installs authored skills, copies sandbox files, and adds agent tool scripts.</p><p>The workspace is a real Cursor project. It can inherit <code>AGENTS.md</code> and <code>.cursor</code> settings from parent directories. Nested git checkouts default <code>local.cwd</code> to a per-project cache directory under <code>~/.cache</code>. Point <code>cwd</code> at a checkout only when the agent should inherit that tree. <code>run</code> and <code>eval</code> already use a temporary state root.</p><p>Session files live under <code>--state-root</code>. See <a href="./reference/sessions.html#where-does-the-agent-sdk-store-session-data">Sessions</a> for the layout.</p><h2 id="how-can-one-agent-call-another" tabindex="-1">How can one agent call another? <a class="header-anchor" href="#how-can-one-agent-call-another" aria-label="Permalink to &quot;How can one agent call another?&quot;">​</a></h2><p>Every mounted agent also serves MCP at <code>/&lt;slug&gt;/v1/mcp</code>. Another agent or MCP client can use <code>ask</code>, <code>check</code>, and <code>call_tool</code> to delegate work. A peer MCP connection such as <code>defineConnection({ agent: &quot;weather-agent&quot; })</code> adds those tools to the calling agent.</p><p>See <a href="./guides/agent-to-agent.html">Agent-to-agent</a> for a complete example.</p><h2 id="which-rules-prevent-common-setup-problems" tabindex="-1">Which rules prevent common setup problems? <a class="header-anchor" href="#which-rules-prevent-common-setup-problems" aria-label="Permalink to &quot;Which rules prevent common setup problems?&quot;">​</a></h2><ul><li>Use Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Put evals under the project-root <code>evals/</code> directory, not <code>agent/evals/</code>.</li><li>Run a TypeScript check before shipping. <code>validate</code> and <code>run</code> execute TypeScript but don&#39;t type-check it.</li><li>Return JSON-shaped values from tool <code>execute</code> functions.</li><li>Keep local session workspaces away from parent rules you don&#39;t want the agent to inherit.</li><li>Sign in or set <code>CURSOR_API_KEY</code> before starting a model turn. Discovery, validation, direct tool calls, and server startup work without a credential.</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Quickstart</a></li><li><a href="./reference/project-layout.html">Project layout</a></li><li><a href="./reference/sessions.html">Sessions and streaming</a></li><li><a href="./reference/channels.html">Channels</a></li><li><a href="./ab.html">Live A/B metrics</a></li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a></li></ul>',42)])])}const m=t(n,[["render",r]]);export{p as __pageData,m as default};

package/dist/docs/assets/example-agents_approval-buddy.md.DmezILPg.js

@@ -1,10 +0,0 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Keep PR approval policy deterministic with Approval Buddy","description":"Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals.","frontmatter":{"title":"Keep PR approval policy deterministic with Approval Buddy","description":"Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals."},"headers":[],"relativePath":"example-agents/approval-buddy.md","filePath":"example-agents/approval-buddy.md"}'),o={name:"example-agents/approval-buddy.md"};function r(l,e,n,d,p,h){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="keep-pr-approval-policy-deterministic-with-approval-buddy" tabindex="-1">Keep PR approval policy deterministic with Approval Buddy <a class="header-anchor" href="#keep-pr-approval-policy-deterministic-with-approval-buddy" aria-label="Permalink to &quot;Keep PR approval policy deterministic with Approval Buddy&quot;">​</a></h1><p>Approval Buddy approves eligible pull requests from a fixed roster and declines every other request. GitHub still blocks self-approval when the stamp identity authored the PR. Code decides eligibility. The model prepares evidence, runs two specialist reviews, and passes their findings to the approval tool without changing the policy decision.</p><p>Use this example when an agent can make a judgment inside a workflow, but authorization and the final side effect must stay in deterministic code.</p><p><a href="./../../examples/approval-buddy/">Browse the Approval Buddy source.</a></p><h2 id="keep-approval-policy-in-code" tabindex="-1">Keep approval policy in code <a class="header-anchor" href="#keep-approval-policy-in-code" aria-label="Permalink to &quot;Keep approval policy in code&quot;">​</a></h2><p>Approval Buddy draws three hard boundaries:</p><ul><li><code>prepare_review</code> and <code>approve_pr</code> re-read the live PR and apply the same eligibility rules.</li><li>Two subagents inspect prepared evidence, but their findings never grant or block approval.</li><li>Only <code>approve_pr</code> posts the GitHub review.</li></ul><p>A spoofed webhook, Slack message, or model claim can&#39;t add someone to the buddy roster. The mutating tool checks the source of truth immediately before it acts.</p><h2 id="follow-the-intended-stamp-flow" tabindex="-1">Follow the intended stamp flow <a class="header-anchor" href="#follow-the-intended-stamp-flow" aria-label="Permalink to &quot;Follow the intended stamp flow&quot;">​</a></h2><p>The root instructions ask the model to run this sequence for a qualifying PR:</p><ol><li>A non-draft <code>pull_request</code> event arrives with action <code>opened</code>, <code>reopened</code>, or <code>ready_for_review</code>.</li><li>The GitHub channel checks its repository allowlist and starts a session.</li><li><code>turn.started</code> posts a pending commit status.</li><li>The model calls <code>prepare_review</code>.</li><li>Host code fetches the live PR. It checks the author, open state, merged state, and draft state.</li><li>A qualifying PR gets <code>pr/MANIFEST.md</code>, <code>pr/meta.json</code>, and <code>pr/diff.patch</code> in the session workspace. Diffs above 2,000,000 characters are truncated and marked in metadata.</li><li>The model calls both review subagents through the built-in <code>task</code> tool.</li><li>It concatenates their contracted replies and calls <code>approve_pr</code>.</li><li><code>approve_pr</code> re-runs eligibility, posts an <code>APPROVE</code> review, and returns the outcome.</li><li>The channel posts a final commit status. A self-approval block also gets a short timeline comment because no approval review can appear.</li></ol><p>Ineligible PRs skip evidence and subagents. The model still calls <code>approve_pr</code> so the deterministic tool returns the formal decline reason.</p><p>Steps 4 through 9 are prompt-driven. The channel doesn&#39;t enforce tool order or prove both subagents ran, and <code>approve_pr</code> accepts missing findings. A failed turn clears the pending status with a green non-blocking result without approving the PR.</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>Root agent and policy prompt</td><td><a href="../../examples/approval-buddy/agent/agent.ts"><code>agent/agent.ts</code></a>, <a href="./../../examples/approval-buddy/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Configure the local agent and describe orchestration order.</td></tr><tr><td>GitHub channel</td><td><a href="../../examples/approval-buddy/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Filter wakes, lease GitHub access, and publish status events.</td></tr><tr><td>Slack channel</td><td><a href="../../examples/approval-buddy/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Accept approval-bot stamp and qualification requests.</td></tr><tr><td>Server tools</td><td><a href="./../../examples/approval-buddy/agent/tools/"><code>agent/tools/</code></a></td><td>Prepare evidence, approve, list buddies, and search GIFs.</td></tr><tr><td>Deterministic policy</td><td><a href="../../examples/approval-buddy/agent/lib/approve.ts"><code>agent/lib/approve.ts</code></a>, <a href="../../examples/approval-buddy/agent/lib/buddies.ts"><code>agent/lib/buddies.ts</code></a></td><td>Own the roster and live eligibility checks.</td></tr><tr><td>Review subagents</td><td><a href="./../../examples/approval-buddy/agent/subagents/"><code>agent/subagents/</code></a></td><td>Run deep audit and code-quality passes over the same evidence.</td></tr><tr><td>Storage</td><td><a href="../../examples/approval-buddy/agent/storage.ts"><code>agent/storage.ts</code></a></td><td>Persist sessions and events with <code>cursorHostedStorage</code>. See <a href="./../storage.html">Storage</a>.</td></tr><tr><td>Live A/B experiment</td><td><a href="../../examples/approval-buddy/agent/ab.ts"><code>agent/ab.ts</code></a></td><td>Compare baseline responses with a concise, presentation-only treatment (<code>concise-results</code>).</td></tr><tr><td>Evals and unit tests</td><td><a href="./../../examples/approval-buddy/evals/"><code>evals/</code></a>, <a href="./../../examples/approval-buddy/agent/lib/"><code>agent/lib/</code></a></td><td>Protect routing, output contracts, policy, and GitHub behavior.</td></tr></tbody></table><p>There are no authored skills, MCP connections, schedules, reminders, hooks, sandbox seeds, or tool approvals.</p><h2 id="prepare-credentials" tabindex="-1">Prepare credentials <a class="header-anchor" href="#prepare-credentials" aria-label="Permalink to &quot;Prepare credentials&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential.</li><li>GitHub access to read PRs, post reviews, create commit statuses, and post the self-approval visibility comment.</li></ul><p>Optional GIF selection uses:</p><ul><li><code>GIPHY_API_KEY</code> or <code>APPROVAL_BUDDY_GIPHY_API_KEY</code>,</li><li><code>APPROVAL_BUDDY_STAMP_GIF</code>, or</li><li>severity-specific <code>APPROVAL_BUDDY_STAMP_GIF_&lt;LEVEL&gt;</code> variables.</li></ul><p>If you enable Giphy in a hosted copy, declare its secret and <code>api.giphy.com</code> egress.</p><h2 id="validate-without-approving-a-pr" tabindex="-1">Validate without approving a PR <a class="header-anchor" href="#validate-without-approving-a-pr" aria-label="Permalink to &quot;Validate without approving a PR&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/approval-buddy</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/approval-buddy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>List the deterministic roster:</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;"> list_buddies</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/approval-buddy</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;{}&#39;</span></span></code></pre></div><p>Set a known merged PR, then run the read-only precheck:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">MERGED_PR_URL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">https://github.com/your-org/your-repo/pull/123</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> prepare_review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/approval-buddy</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;"> &quot;{</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">prUrl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$MERGED_PR_URL</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&quot;</span></span></code></pre></div><p>The result should decline because the PR is no longer open. <code>prepare_review</code> never posts an approval.</p><div class="caution custom-block github-alert"><p class="custom-block-title">CAUTION</p><p>Don&#39;t use <code>agent-sdk call approve_pr</code> as a smoke test. The tool has no <code>needsApproval</code> gate and posts a real GitHub review when the PR qualifies.</p></div><h2 id="see-why-preparation-is-separate" tabindex="-1">See why preparation is separate <a class="header-anchor" href="#see-why-preparation-is-separate" aria-label="Permalink to &quot;See why preparation is separate&quot;">​</a></h2><p><code>prepare_review</code> is read-only. It checks policy before fetching a large diff, so declined requests don&#39;t spend review-agent work.</p><p>Direct calls return the evidence file map because their scratch workspace is deleted after the call. In-session calls write the tree to <code>ctx.workspaceDir</code>, where both subagents can read it.</p><p><code>approve_pr</code> repeats the live check instead of trusting preparation. A PR can close, merge, become a draft, or change author-related context between the two steps. Revalidation keeps the final write bound to current state.</p><p>This is a reusable two-tool pattern:</p><ul><li>a read-only tool prepares and explains the decision,</li><li>a mutating tool repeats policy at the side-effect boundary.</li></ul><h2 id="fan-out-two-review-contracts" tabindex="-1">Fan out two review contracts <a class="header-anchor" href="#fan-out-two-review-contracts" aria-label="Permalink to &quot;Fan out two review contracts&quot;">​</a></h2><p>The two discovered subagents have different contracts:</p><ul><li>The security reviewer reports bugs, breaking changes, and security findings with <code>High</code>, <code>Medium</code>, or <code>Low</code> tags.</li><li>The code-quality reviewer reports maintainability and structure concerns with <code>Blocker</code>, <code>Major</code>, or <code>Minor</code> tags.</li></ul><p>The parent calls both through the harness <code>task</code> tool. They inherit the root agent&#39;s execution surface and read the same <code>pr/</code> workspace. The prompt asks the parent not to rewrite either reply. The review body trims the combined text and caps it at 16,000 characters.</p><p>Findings are informational. A high-severity finding doesn&#39;t veto the stamp. That policy is explicit in the root instructions and approval code.</p><h2 id="trace-github-channel-behavior" tabindex="-1">Trace GitHub channel behavior <a class="header-anchor" href="#trace-github-channel-behavior" aria-label="Permalink to &quot;Trace GitHub channel behavior&quot;">​</a></h2><p>The channel uses <code>githubChannel</code> with:</p><ul><li>a configured repository allowlist on the account-linked GitHub transport,</li><li>a second optional <code>APPROVAL_BUDDY_REPOS</code> wake filter,</li><li><code>deliverReplies: false</code>,</li><li>progress reactions disabled, and</li><li>event handlers for turn start, <code>approve_pr</code> results, and failed turns.</li></ul><p>The source requests <code>contents-write</code>, even though the documented workflow posts reviews, statuses, and comments. When adapting the example, start with <code>pr-write</code> and opt up only if a tool must push code.</p><p>Every terminal status is green by design. Declines and crashed turns are informational, not merge-blocking. This is a product decision in the example, not an Agent SDK default.</p><p>A successful turn that never calls <code>approve_pr</code> leaves the pending status in place. The channel clears it on <code>approve_pr</code> results and <code>turn.failed</code>, but has no <code>turn.completed</code> fallback.</p><p><code>github replay</code> reaches the same channel and can post a real approval, status, or comment. Use replay only against a repository and PR created for this test.</p><h2 id="use-slack-for-explicit-requests" tabindex="-1">Use Slack for explicit requests <a class="header-anchor" href="#use-slack-for-explicit-requests" aria-label="Permalink to &quot;Use Slack for explicit requests&quot;">​</a></h2><p>Start the dev server:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/approval-buddy</span></span></code></pre></div><p>Then ask through the signed-in account-linked Slack connection:</p><blockquote><p>Would this PR qualify for a stamp?</p></blockquote><p>The instructions route qualification questions to <code>prepare_review</code> only. A stamp request runs the complete flow and may approve the PR.</p><p>This channel uses the account-linked transport instead of a dedicated Socket Mode app.</p><h2 id="see-how-durable-storage-fits" tabindex="-1">See how durable storage fits <a class="header-anchor" href="#see-how-durable-storage-fits" aria-label="Permalink to &quot;See how durable storage fits&quot;">​</a></h2><p><code>defineStorage</code> replaces the default local session store with a shared, durable key-value adapter. Approval Buddy chooses:</p><ul><li>a 15-second write debounce,</li><li>startup restoration for up to 200 sessions, and</li><li>a 14-day restore window.</li></ul><p>That policy fits long-lived Slack threads and a small webhook fleet. The security reviewer uses the same adapter with lazy restore, which fits its shorter sessions.</p><h2 id="run-the-regression-suite" tabindex="-1">Run the regression suite <a class="header-anchor" href="#run-the-regression-suite" aria-label="Permalink to &quot;Run the regression suite&quot;">​</a></h2><p>List the four eval cases:</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/approval-buddy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span></code></pre></div><p>The suite covers:</p><ul><li>buddy-list routing,</li><li>declining a merged PR,</li><li>using only <code>prepare_review</code> for a qualification question, and</li><li>the combined findings headings and severity format over seeded evidence.</li></ul><p>Run the safe qualification case:</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;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/approval-buddy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  qualify/merged-pr-question</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --json</span></span></code></pre></div><p>The qualification case reads a live merged PR. The seeded format case shown by <code>--list</code> uses a planted auth-bypass diff and checks for a <code>task</code> call, both headings, and severity tags. It doesn&#39;t prove both named subagents ran or whether their output reached <code>approve_pr</code>. Unit tests under <code>agent/lib/</code> cover policy, self-approval handling, evidence limits, status mapping, GIF selection, and severity parsing.</p><h2 id="reuse-the-policy-boundary" tabindex="-1">Reuse the policy boundary <a class="header-anchor" href="#reuse-the-policy-boundary" aria-label="Permalink to &quot;Reuse the policy boundary&quot;">​</a></h2><p>Keep these properties when you replace the buddy policy:</p><ol><li>Put authorization in typed code.</li><li>Fetch the source of truth inside both prepare and mutate steps.</li><li>Give the model evidence only after the request qualifies.</li><li>Treat specialist findings as data, not authority.</li><li>Keep the core domain mutation in one named tool. Treat channel status and visibility writes as separate, audited effects.</li><li>Add a human approval gate if your policy still needs operator consent.</li><li>Test read-only routing separately from mutation.</li></ol><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/github.html">GitHub</a></li><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/subagents.html">Subagents</a></li><li><a href="./../storage.html">Storage</a></li><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,72)])])}const k=a(o,[["render",r]]);export{u as __pageData,k as default};

package/dist/docs/assets/example-agents_approval-buddy.md.DmezILPg.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Keep PR approval policy deterministic with Approval Buddy","description":"Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals.","frontmatter":{"title":"Keep PR approval policy deterministic with Approval Buddy","description":"Separate code-owned eligibility from model-owned review, then connect GitHub, Slack, subagents, durable storage, and evals."},"headers":[],"relativePath":"example-agents/approval-buddy.md","filePath":"example-agents/approval-buddy.md"}'),o={name:"example-agents/approval-buddy.md"};function r(l,e,n,d,p,h){return s(),t("div",null,[...e[0]||(e[0]=[i("",72)])])}const k=a(o,[["render",r]]);export{u as __pageData,k as default};

package/dist/docs/assets/example-agents_benny.md.B0kwY7D_.js

@@ -1,5 +0,0 @@
-import{_ as a,c as t,o as s,ag as o}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Route Slack work through repository playbooks","description":"Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace.","frontmatter":{"title":"Route Slack work through repository playbooks","description":"Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace."},"headers":[],"relativePath":"example-agents/benny.md","filePath":"example-agents/benny.md"}'),i={name:"example-agents/benny.md"};function n(l,e,r,h,d,c){return s(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="route-slack-work-through-repository-playbooks" tabindex="-1">Route Slack work through repository playbooks <a class="header-anchor" href="#route-slack-work-through-repository-playbooks" aria-label="Permalink to &quot;Route Slack work through repository playbooks&quot;">​</a></h1><p>This agent is a Slack teammate for a product team. Mentions and direct messages reach it through an account-linked transport. New top-level posts in an allowlisted issue channel reach it through a dedicated Slack app, even without a mention. The agent then selects a repository playbook for triage, reproduction, fixes, reviews, on-call work, or design critique.</p><p>Use this example when Slack is the intake surface and your durable procedures already live as repository skills.</p><p><a href="./../../examples/benny/">Browse the current playbook-router source.</a></p><h2 id="combine-two-slack-transports-with-repo-skills" tabindex="-1">Combine two Slack transports with repo skills <a class="header-anchor" href="#combine-two-slack-transports-with-repo-skills" aria-label="Permalink to &quot;Combine two Slack transports with repo skills&quot;">​</a></h2><p>The playbook router uniquely combines three decisions:</p><ul><li>Two Slack transports serve different engagement modes.</li><li><code>local.cwd</code> keeps session workspaces inside the monorepo.</li><li>Instructions route work to inherited repository playbooks instead of authored <code>agent/skills/</code>.</li></ul><p>The result is a thin agent project over a mature procedure library.</p><h2 id="follow-an-issue-report" tabindex="-1">Follow an issue report <a class="header-anchor" href="#follow-an-issue-report" aria-label="Permalink to &quot;Follow an issue report&quot;">​</a></h2><ol><li>A teammate creates a top-level post in the allowlisted issue channel.</li><li>The dedicated Socket Mode channel accepts the allowlisted channel.</li><li>A 15-second debounce lets edits settle. Deleting the post during that window cancels the dispatch.</li><li>The Agent SDK creates a thread-scoped session and sends the report to the playbook router.</li><li>The instructions select the matching triage playbook.</li><li>The harness finds the repository root, opens the inherited playbook, and follows its procedure.</li><li>The agent posts only in the source thread and reports the evidence it gathered.</li></ol><p>Mentions and direct messages follow the same agent instructions. They don&#39;t need the watched-channel path.</p><h2 id="map-the-playbook-router-files" tabindex="-1">Map the playbook router files <a class="header-anchor" href="#map-the-playbook-router-files" aria-label="Permalink to &quot;Map the playbook router files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/benny/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Names the agent, selects its model, and points the harness at a project-local cwd so inherited playbooks load.</td></tr><tr><td><a href="./../../examples/benny/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Defines engagement rules, evidence policy, and the playbook routing map.</td></tr><tr><td><a href="../../examples/benny/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Handles account-linked mentions and direct messages.</td></tr><tr><td><a href="../../examples/benny/agent/channels/slack-app.ts"><code>agent/channels/slack-app.ts</code></a></td><td>Runs the dedicated app and watches one allowlisted channel.</td></tr><tr><td><a href="../../examples/benny/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/benny/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/benny/evals/smoke.eval.ts"><code>evals/smoke.eval.ts</code></a></td><td>Checks the agent identity and expected triage route.</td></tr></tbody></table><p>The playbook router authors no tools, MCP connections, subagents, schedules, hooks, A/B experiments, or sandbox seeds.</p><h2 id="see-why-local-cwd-matters" tabindex="-1">See why <code>local.cwd</code> matters <a class="header-anchor" href="#see-why-local-cwd-matters" aria-label="Permalink to &quot;See why \`local.cwd\` matters&quot;">​</a></h2><p>The Agent SDK normally keeps an ephemeral <code>run</code> or <code>eval</code> workspace outside a large monorepo. This prevents ancestor instruction and repository-rule files from leaking into an unrelated agent.</p><p>The playbook router needs the opposite. Its procedures live at the repository root, so <code>agent.ts</code> points <code>local.cwd</code> at a harness directory under the project. Each harness workspace is a child of that directory. Walking up reaches the host repository and its inherited playbook directory.</p><p>Those playbooks are inherited context. <code>agent-sdk info</code> reports zero authored skills for the agent. Copying this project into another repository removes its main procedures unless you copy or replace the skill library too.</p><h2 id="connect-both-slack-paths" tabindex="-1">Connect both Slack paths <a class="header-anchor" href="#connect-both-slack-paths" aria-label="Permalink to &quot;Connect both Slack paths&quot;">​</a></h2><p>The account-linked path needs an agent-runtime login and a connected Slack 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>It routes explicit mentions without a dedicated Slack token on the host.</p><p>For the watched-channel path, configure a dedicated Socket Mode app with:</p><ul><li>subscribe to <code>message.channels</code> and <code>message.groups</code>,</li><li>have an App-Level Token with <code>connections:write</code>, and</li><li>be a member of the watched channel.</li></ul><p>Run <code>agent-sdk slack create --dir examples/benny --channel-posts</code> for a dedicated Socket Mode app, then <code>agent-sdk slack doctor</code>.</p><p>Missing dedicated-app tokens leave that channel idle. They don&#39;t stop the account-linked channel.</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/benny</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/benny</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/benny</span></span></code></pre></div><p>The info output should show two Slack channels and no authored skill. That combination confirms the example is using inherited playbooks.</p><h2 id="exercise-each-engagement-mode" tabindex="-1">Exercise each engagement mode <a class="header-anchor" href="#exercise-each-engagement-mode" aria-label="Permalink to &quot;Exercise each engagement mode&quot;">​</a></h2><p>Test the explicit account-linked path by asking:</p><blockquote><p>Which playbook would you use to triage a product UI bug?</p></blockquote><p>Test the dedicated app:</p><ol><li>Create a top-level post in the allowlisted issue channel.</li><li>Don&#39;t mention the bot.</li><li>Wait for the debounce window.</li><li>Confirm the agent replies in the post&#39;s thread.</li></ol><p>Thread replies don&#39;t trigger the proactive watch. Mentions still use Slack&#39;s normal mention path. Bot-authored posts are ignored to prevent loops.</p><p>The channel uses the default handler after filtering. It doesn&#39;t apply a second code-level classifier, so every accepted top-level post spends a model turn and reaches the prompt.</p><h2 id="inspect-thread-continuity" tabindex="-1">Inspect thread continuity <a class="header-anchor" href="#inspect-thread-continuity" aria-label="Permalink to &quot;Inspect thread continuity&quot;">​</a></h2><p>The Agent SDK keys Slack sessions by channel and thread timestamp. A follow-up in the same thread resumes the conversation and workspace. A new top-level issue gets a new session.</p><p>This lets a playbook gather evidence over several turns without mixing two reports. The playground shows both the account-linked and dedicated-app sessions while the dev server runs.</p><h2 id="run-the-smoke-eval" tabindex="-1">Run the smoke eval <a class="header-anchor" href="#run-the-smoke-eval" aria-label="Permalink to &quot;Run the smoke eval&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/benny</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/benny</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The case asks for the agent identity and the playbook used for issue triage. It checks the configured identity and route label.</p><p>This is a lexical smoke test. It doesn&#39;t prove Slack delivery, skill selection, skill loading, procedure execution, or thread-only behavior. Add fixture-backed evals around the playbooks when you reuse this design.</p><h2 id="build-a-playbook-routed-teammate" tabindex="-1">Build a playbook-routed teammate <a class="header-anchor" href="#build-a-playbook-routed-teammate" aria-label="Permalink to &quot;Build a playbook-routed teammate&quot;">​</a></h2><p>Use this structure when your organization already has tested skills:</p><ol><li>Put the playbooks under a stable repository path.</li><li>Set <code>local.cwd</code> so harness workspaces can inherit that path.</li><li>Write a short routing table in <code>instructions.md</code>.</li><li>Use account-linked Slack for explicit requests.</li><li>Add a dedicated app only for allowlisted proactive intake.</li><li>Keep the channel allowlist narrow and debounce edited posts.</li><li>Add an eval for every important request-to-playbook route.</li></ol><p>If the procedures should ship with the agent, put them under <code>agent/skills/</code> instead. Authored skills appear in the manifest and travel with the project.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../reference/agent-config.html">Agent config</a></li><li><a href="./../reference/skills.html">Skills</a></li><li><a href="./../reference/sessions.html">Sessions and streaming</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,49)])])}const u=a(i,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/example-agents_benny.md.B0kwY7D_.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as t,o as s,ag as o}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Route Slack work through repository playbooks","description":"Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace.","frontmatter":{"title":"Route Slack work through repository playbooks","description":"Combine account-linked chat, allowlisted Socket Mode channel watching, inherited repository skills, and a custom local workspace."},"headers":[],"relativePath":"example-agents/benny.md","filePath":"example-agents/benny.md"}'),i={name:"example-agents/benny.md"};function n(l,e,r,h,d,c){return s(),t("div",null,[...e[0]||(e[0]=[o("",49)])])}const u=a(i,[["render",n]]);export{k as __pageData,u as default};

package/dist/docs/assets/example-agents_bugbot.md.BRGMi9O2.js

@@ -1,11 +0,0 @@
-import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Review prepared pull-request evidence","description":"Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval.","frontmatter":{"title":"Review prepared pull-request evidence","description":"Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval."},"headers":[],"relativePath":"example-agents/bugbot.md","filePath":"example-agents/bugbot.md"}'),r={name:"example-agents/bugbot.md"};function n(l,e,o,h,d,p){return s(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="review-prepared-pull-request-evidence" tabindex="-1">Review prepared pull-request evidence <a class="header-anchor" href="#review-prepared-pull-request-evidence" aria-label="Permalink to &quot;Review prepared pull-request evidence&quot;">​</a></h1><p>This GitHub-read-only reviewer uses host code to fetch the PR with <code>gh</code> and <code>git</code>, builds a trimmed <code>pr/</code> evidence tree, then hands that tree to the model. The model reads the diff, loads a review skill, and returns at most three high-confidence findings.</p><p>Use this example when the host should control evidence collection and the model shouldn&#39;t browse or mutate the source repository.</p><p><a href="./../../examples/bugbot/">Browse the current reviewer source.</a></p><h2 id="separate-evidence-preparation-from-review" tabindex="-1">Separate evidence preparation from review <a class="header-anchor" href="#separate-evidence-preparation-from-review" aria-label="Permalink to &quot;Separate evidence preparation from review&quot;">​</a></h2><p>The reviewer separates preparation from judgment:</p><ul><li>Host code owns GitHub and Git access.</li><li>A server tool turns untrusted PR input into bounded workspace files.</li><li>A custom channel seeds those files before the model starts.</li><li>An on-demand skill defines the review procedure and output contract.</li><li>The model returns chat text. No path posts a GitHub review.</li></ul><p>This architecture gives the model a purpose-built evidence package instead of a checkout.</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><p>The custom HTTP path runs this sequence:</p><ol><li><code>POST /v1/channels/review/</code> receives a PR reference.</li><li>The handler calls <code>prepare_pr</code> without a model turn.</li><li>Host code reads PR metadata and the unified diff.</li><li>It reuses a matching checkout, force-fetching the PR ref there when the commit is missing. Without a matching checkout, it uses a temporary bare cache.</li><li>It creates <code>pr/MANIFEST.md</code>, <code>pr/meta.json</code>, <code>pr/diff.patch</code>, and selected small files and rules.</li><li><code>send({ workspaceFiles })</code> creates the model session with that evidence.</li><li>The model reads the manifest and diff, then loads <code>pr-review</code>.</li><li>The channel returns session and playground URLs while the review streams.</li></ol><p>If a normal chat starts without evidence, the model can call <code>prepare_pr</code> mid-turn. That form writes the same files into the active session workspace.</p><h2 id="map-the-evidence-review-files" tabindex="-1">Map the evidence-review files <a class="header-anchor" href="#map-the-evidence-review-files" aria-label="Permalink to &quot;Map the evidence-review files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/bugbot/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Selects the local runtime and model.</td></tr><tr><td><a href="./../../examples/bugbot/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Requires diff-first review and confines model work to <code>pr/</code>.</td></tr><tr><td><a href="../../examples/bugbot/agent/tools/prepare_pr.ts"><code>agent/tools/prepare_pr.ts</code></a></td><td>Exposes host preparation as a typed server tool.</td></tr><tr><td><a href="../../examples/bugbot/agent/lib/prepare-pr.ts"><code>agent/lib/prepare-pr.ts</code></a></td><td>Parses PR references, runs <code>gh</code> and <code>git</code>, and builds the evidence map.</td></tr><tr><td><a href="../../examples/bugbot/agent/channels/review.ts"><code>agent/channels/review.ts</code></a></td><td>Provides the loopback-only prepare-and-send HTTP route.</td></tr><tr><td><a href="../../examples/bugbot/agent/channels/slack.ts"><code>agent/channels/slack.ts</code></a></td><td>Extracts PR references and prepares evidence for mentions and direct messages.</td></tr><tr><td><a href="./../../examples/bugbot/agent/skills/pr-review.html"><code>agent/skills/pr-review.md</code></a></td><td>Sets finding limits, severities, and the machine-readable review format.</td></tr><tr><td><a href="../../examples/bugbot/agent/lib/log.ts"><code>agent/lib/log.ts</code></a></td><td>Writes timing logs for the host tools to stderr.</td></tr><tr><td><a href="../../examples/bugbot/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/bugbot/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/bugbot/evals/review/smoke.eval.ts"><code>evals/review/smoke.eval.ts</code></a></td><td>Seeds fake evidence and checks the review path without GitHub.</td></tr></tbody></table><p>There is no authored GitHub channel, MCP connection, subagent, schedule, hook, A/B experiment, approval, or custom storage.</p><h2 id="prepare-the-host" tabindex="-1">Prepare the host <a class="header-anchor" href="#prepare-the-host" aria-label="Permalink to &quot;Prepare the host&quot;">​</a></h2><p>You need:</p><ul><li>Node 22.13 or newer.</li><li>An agent-runtime credential for model turns and account-linked Slack.</li><li><code>gh</code> and <code>git</code> on <code>PATH</code>.</li><li><code>gh</code> access to the target PR.</li><li>Network access to GitHub and a writable temporary directory.</li></ul><p>The preparer can prefer a configured local checkout. Its <code>origin</code> must match the target repository. Otherwise the reviewer uses its bare cache. It never checks out the PR into the serve host&#39;s working tree.</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/bugbot</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/bugbot</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The manifest should show one server tool, one skill, and two authored channels.</p><h2 id="inspect-evidence-without-a-model-turn" tabindex="-1">Inspect evidence without a model turn <a class="header-anchor" href="#inspect-evidence-without-a-model-turn" aria-label="Permalink to &quot;Inspect evidence without a model turn&quot;">​</a></h2><p>Call the preparation tool directly:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> prepare_pr</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/bugbot</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;pr&quot;:&quot;https://github.com/owner/repo/pull/123&quot;}&#39;</span></span></code></pre></div><p>Direct tool calls use a scratch workspace removed after the call. <code>prepare_pr</code> detects this path and returns the complete file map in its result. In a model session, it writes the files and returns a smaller summary.</p><p>The evidence builder applies explicit limits:</p><table tabindex="0"><thead><tr><th>Evidence</th><th>Limit</th></tr></thead><tbody><tr><td>Post-change file</td><td>12,000 characters</td></tr><tr><td>One rule file</td><td>8,000 characters</td></tr><tr><td>Combined rules</td><td>12,000 characters</td></tr><tr><td>PR body in metadata</td><td>2,000 characters</td></tr></tbody></table><p>Large files remain visible in <code>diff.patch</code>. The manifest records which full files or rules were omitted.</p><p>The per-file limits aren&#39;t an aggregate context cap. Every changed file below 12,000 characters can be included. The diff command has a 12 MiB output buffer; a larger diff fails preparation instead of being truncated.</p><h2 id="run-the-http-review-path" tabindex="-1">Run the HTTP review path <a class="header-anchor" href="#run-the-http-review-path" aria-label="Permalink to &quot;Run the HTTP review path&quot;">​</a></h2><p>Start the server:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/bugbot</span></span></code></pre></div><p>From another terminal:</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/bugbot/v1/channels/review/</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;pr&quot;:&quot;https://github.com/owner/repo/pull/123&quot;}&#39;</span></span></code></pre></div><p>The route returns <code>status: &quot;started&quot;</code>, a continuation token, and session and playground URLs. Open the session URL to watch the model read the evidence and produce findings.</p><p>The channel declares <code>localDevStrict()</code>. Direct loopback callers can use it. Proxy-forwarding headers and non-loopback hosts are rejected.</p><p>Send a follow-up by passing the returned key:</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/bugbot/v1/channels/review/</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;pr&quot;:&quot;owner/repo#123&quot;,&quot;key&quot;:&quot;&lt;continuation-token&gt;&quot;}&#39;</span></span></code></pre></div><p>The follow-up resumes the session without fetching a new evidence tree.</p><h2 id="run-the-slack-path" tabindex="-1">Run the Slack path <a class="header-anchor" href="#run-the-slack-path" aria-label="Permalink to &quot;Run the Slack path&quot;">​</a></h2><p>The account-linked Slack channel handles review-bot mentions and direct messages:</p><blockquote><p>Review <a href="https://github.com/owner/repo/pull/123" target="_blank" rel="noreferrer">https://github.com/owner/repo/pull/123</a></p></blockquote><p>Slack handlers don&#39;t receive the channel <code>callTool</code> helper. This example calls the shared <code>preparePrReview</code> host function, then returns <code>workspaceFiles</code> in the Slack message preparation result. The model sees the same evidence and prompt as the HTTP path.</p><p>If a message contains no PR reference, the handler asks for one. Thread follow-ups keep the same session.</p><h2 id="see-how-the-skill-constrains-review" tabindex="-1">See how the skill constrains review <a class="header-anchor" href="#see-how-the-skill-constrains-review" aria-label="Permalink to &quot;See how the skill constrains review&quot;">​</a></h2><p><code>pr-review.md</code> tells the model to:</p><ul><li>read the manifest and unified diff first,</li><li>open at most one supporting file or rules file when a hunk is ambiguous,</li><li>avoid shell, network, <code>gh</code>, and <code>git</code>,</li><li>report no more than three findings,</li><li>keep each description under 120 words, and</li><li>emit the machine-readable review contract.</li></ul><p>The root instructions set the evidence boundary. The skill holds the reusable review procedure. Keeping those roles separate lets another agent reuse the same skill with different intake channels.</p><h2 id="run-the-fixture-backed-eval" tabindex="-1">Run the fixture-backed eval <a class="header-anchor" href="#run-the-fixture-backed-eval" aria-label="Permalink to &quot;Run the fixture-backed eval&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/bugbot</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/bugbot</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> review/smoke</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The eval constructs a <code>PreparedPrReview</code>, seeds its file map through <code>workspaceFiles</code>, and checks for at least one read call with no shell call. It doesn&#39;t assert which evidence file was read or whether the skill loaded. It accepts either a formatted review or a clean result.</p><p>This case tests review behavior without GitHub credentials or network data. Add fixtures with reachable bugs when you need stricter location and severity checks.</p><h2 id="keep-the-side-effect-boundary-clear" tabindex="-1">Keep the side-effect boundary clear <a class="header-anchor" href="#keep-the-side-effect-boundary-clear" aria-label="Permalink to &quot;Keep the side-effect boundary clear&quot;">​</a></h2><p>The reviewer makes no remote GitHub writes. It doesn&#39;t author a GitHub channel and doesn&#39;t call a review API. Host preparation does write session evidence and force-update <code>refs/pull/&lt;N&gt;/head</code> in either its bare cache or a matching local checkout when the commit is missing. Every result ends with a note saying no GitHub review was posted.</p><p>If you add publishing later, keep it in a separate tool. This preserves a read-only preparation and review path safe to run in evals.</p><h2 id="reuse-the-evidence-handoff" tabindex="-1">Reuse the evidence handoff <a class="header-anchor" href="#reuse-the-evidence-handoff" aria-label="Permalink to &quot;Reuse the evidence handoff&quot;">​</a></h2><p>Use host-prepared workspaces when:</p><ul><li>external APIs should stay off the model&#39;s tool surface,</li><li>context needs hard size limits,</li><li>the model should inspect a snapshot instead of a live checkout, or</li><li>several channels need the same preparation.</li></ul><p>Return <code>workspaceFiles</code> from direct host preparation, write into <code>ctx.workspaceDir</code> for mid-turn recovery, and encode the reading order in both the manifest and a skill.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/webhooks.html">Webhooks and custom channels</a></li><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../reference/skills.html">Skills</a></li><li><a href="./../guides/slack.html">Slack</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,62)])])}const k=t(r,[["render",n]]);export{u as __pageData,k as default};

package/dist/docs/assets/example-agents_bugbot.md.BRGMi9O2.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const u=JSON.parse('{"title":"Review prepared pull-request evidence","description":"Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval.","frontmatter":{"title":"Review prepared pull-request evidence","description":"Fetch a PR on the host, seed a trimmed diff-first workspace, and run a GitHub-read-only review through HTTP, Slack, or an eval."},"headers":[],"relativePath":"example-agents/bugbot.md","filePath":"example-agents/bugbot.md"}'),r={name:"example-agents/bugbot.md"};function n(l,e,o,h,d,p){return s(),a("div",null,[...e[0]||(e[0]=[i("",62)])])}const k=t(r,[["render",n]]);export{u as __pageData,k as default};

package/dist/docs/assets/example-agents_codebase-wiki.md.BBNw9Ekr.js

@@ -1,8 +0,0 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Build a feature wiki from merged pull requests","description":"Ingest every merged PR into per-feature wiki pages, consolidate with a daily digest schedule, and answer codebase questions with page citations.","frontmatter":{"title":"Build a feature wiki from merged pull requests","description":"Ingest every merged PR into per-feature wiki pages, consolidate with a daily digest schedule, and answer codebase questions with page citations."},"headers":[],"relativePath":"example-agents/codebase-wiki.md","filePath":"example-agents/codebase-wiki.md"}'),n={name:"example-agents/codebase-wiki.md"};function d(o,e,r,l,h,c){return t(),s("div",null,[...e[0]||(e[0]=[i(`<h1 id="build-a-feature-wiki-from-merged-pull-requests" tabindex="-1">Build a feature wiki from merged pull requests <a class="header-anchor" href="#build-a-feature-wiki-from-merged-pull-requests" aria-label="Permalink to &quot;Build a feature wiki from merged pull requests&quot;">​</a></h1><p>Codebase wiki keeps a living, feature-organized wiki of a repository. The GitHub channel acknowledges every closed pull request instantly, fetches a compact digest on the host, and spends a model turn only on merged PRs. The turn maps the change onto feature pages; a daily schedule writes a digest of what changed and rebuilds the index. Chat sessions answer codebase questions from the wiki with page citations.</p><p>Use this project when documentation should accumulate from merges instead of being regenerated from scratch. Use <a href="./knowledge-base.html">Knowledge base</a> when people should curate organizational context through conversation.</p><p><a href="./../../examples/codebase-wiki/">Browse the codebase wiki source.</a></p><h2 id="treat-prs-as-evidence-and-features-as-pages" tabindex="-1">Treat PRs as evidence and features as pages <a class="header-anchor" href="#treat-prs-as-evidence-and-features-as-pages" aria-label="Permalink to &quot;Treat PRs as evidence and features as pages&quot;">​</a></h2><p>The wiki refuses to become a merge log:</p><ul><li>The page tree is rigid: <code>index</code>, <code>features/&lt;slug&gt;</code>, and <code>digests/&lt;yyyy-mm-dd&gt;</code>. The store rejects anything else, so the wiki can&#39;t sprawl.</li><li>The <code>feature-mapping</code> skill requires a <code>wiki_search</code> before every write. A PR updates the page that owns its feature; a new page needs a genuinely new feature; chores change nothing.</li><li>Every touched page gets a dated changelog entry citing the PR number, so each fact traces back to a merge.</li></ul><p>The wiki itself is markdown on the serve host, in a wiki directory by default with a <code>CODEBASE_WIKI_DIR</code> override. Sessions are disposable; the wiki is the durable state.</p><h2 id="follow-a-merged-pr" tabindex="-1">Follow a merged PR <a class="header-anchor" href="#follow-a-merged-pr" aria-label="Permalink to &quot;Follow a merged PR&quot;">​</a></h2><ol><li>GitHub delivers <code>pull_request</code> with action <code>closed</code>. The channel returns a task acknowledgement immediately.</li><li>The task fetches the digest with the host <code>gh</code> CLI: title, body, labels, changed files, and a bounded diff excerpt. No checkout.</li><li>The webhook payload can&#39;t say whether the PR merged, so the host checks <code>mergedAt</code> and skips abandoned PRs without a model turn.</li><li>For merged PRs, the task starts the turn with <code>pr/DIGEST.md</code> seeded through <code>workspaceFiles</code> and a <code>pr:&lt;owner/repo#N&gt;</code> continuation token, so redeliveries resume instead of double-ingesting.</li><li>The model follows <code>feature-mapping</code>: search, update or create feature pages, add changelog entries, and refresh <code>index</code> when pages were added.</li></ol><p>In chat, &quot;ingest PR #123&quot; runs the same flow through the <code>ingest_pr</code> tool, which writes the digest into the active session workspace.</p><h2 id="map-the-wiki-files" tabindex="-1">Map the wiki files <a class="header-anchor" href="#map-the-wiki-files" aria-label="Permalink to &quot;Map the wiki files&quot;">​</a></h2><table tabindex="0"><thead><tr><th>File</th><th>Purpose</th></tr></thead><tbody><tr><td><a href="../../examples/codebase-wiki/agent/agent.ts"><code>agent/agent.ts</code></a></td><td>Selects the local runtime and model.</td></tr><tr><td><a href="./../../examples/codebase-wiki/agent/instructions.html"><code>agent/instructions.md</code></a></td><td>Splits the job into merge ingestion and wiki-cited Q&amp;A.</td></tr><tr><td><a href="../../examples/codebase-wiki/agent/lib/wiki-store.ts"><code>agent/lib/wiki-store.ts</code></a></td><td>Enforces the rigid page tree and owns reads, writes, and search.</td></tr><tr><td><a href="../../examples/codebase-wiki/agent/lib/pr-digest.ts"><code>agent/lib/pr-digest.ts</code></a></td><td>Fetches PR metadata and diff, and formats <code>pr/DIGEST.md</code>.</td></tr><tr><td><a href="../../examples/codebase-wiki/agent/tools/ingest_pr.ts"><code>agent/tools/ingest_pr.ts</code></a></td><td>Exposes host digest preparation for chat-driven backfills.</td></tr><tr><td><a href="../../examples/codebase-wiki/agent/tools/wiki_read.ts"><code>agent/tools/wiki_read.ts</code></a>, <a href="../../examples/codebase-wiki/agent/tools/wiki_search.ts"><code>wiki_search.ts</code></a>, <a href="../../examples/codebase-wiki/agent/tools/wiki_write.ts"><code>wiki_write.ts</code></a></td><td>Read, search, and rewrite wiki pages.</td></tr><tr><td><a href="./../../examples/codebase-wiki/agent/skills/feature-mapping.html"><code>agent/skills/feature-mapping.md</code></a></td><td>Maps changes onto features and fixes the page and changelog shape.</td></tr><tr><td><a href="./../../examples/codebase-wiki/agent/schedules/daily-digest.html"><code>agent/schedules/daily-digest.md</code></a></td><td>Writes <code>digests/&lt;date&gt;</code>, rebuilds the index, and flags stale pages.</td></tr><tr><td><a href="../../examples/codebase-wiki/agent/channels/github.ts"><code>agent/channels/github.ts</code></a></td><td>Acknowledges closed PRs and starts merged-only ingest turns.</td></tr><tr><td><a href="../../examples/codebase-wiki/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/codebase-wiki/evals/evals.config.ts"><code>evals/evals.config.ts</code></a></td><td>Caps eval run concurrency.</td></tr><tr><td><a href="../../examples/codebase-wiki/evals/ingest.eval.ts"><code>evals/ingest.eval.ts</code></a></td><td>Gates ingest decisions against the wiki filesystem.</td></tr></tbody></table><p>There is no MCP connection, subagent, hook, or A/B experiment.</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 the PRs you ingest.</li></ul><p>The channel verifies webhook signatures when <code>GITHUB_WEBHOOK_SECRET</code> is set and narrows repositories with <code>CODEBASE_WIKI_REPOS=owner/repo,owner/other</code>. The agent never writes to GitHub. Its only side effects are wiki files on the serve host.</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/codebase-wiki</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/codebase-wiki</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p>The manifest should report four server tools, one skill, one schedule, and the authored GitHub channel.</p><h2 id="ingest-without-webhook-plumbing" tabindex="-1">Ingest without webhook plumbing <a class="header-anchor" href="#ingest-without-webhook-plumbing" aria-label="Permalink to &quot;Ingest without webhook plumbing&quot;">​</a></h2><p>Replay a real merged PR as a closed delivery:</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/codebase-wiki</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/owner/repo/pull/123</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/codebase-wiki</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> closed</span></span></code></pre></div><p>The reply is a 202 acknowledgement; the ingest continues in the task. Watch the session in the playground, then open the wiki directory on the serve host. Feature pages land under <code>features/</code>.</p><p>Each ingested feature page carries an overview, a &quot;How it works&quot; section, and a changelog line citing the PR. Deterministic digest preparation works without a model turn:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ingest_pr</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/codebase-wiki</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;pr&quot;:&quot;https://github.com/owner/repo/pull/123&quot;}&#39;</span></span></code></pre></div><p>A PR closed without merging returns <code>merged: false</code> and a note telling the model to change nothing.</p><h2 id="run-the-daily-digest" tabindex="-1">Run the daily digest <a class="header-anchor" href="#run-the-daily-digest" aria-label="Permalink to &quot;Run the daily digest&quot;">​</a></h2><p>The schedule fires at 07:00 UTC. Under <code>agent-sdk dev</code>, trigger it by hand:</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:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/codebase-wiki/v1/dev/schedules/daily-digest</span></span></code></pre></div><p>The turn reads every feature changelog, writes <code>digests/&lt;today&gt;</code> grouped by feature with PR citations, rebuilds <code>index</code>, and reports one line per page it wrote. Entries dated today always count; a digest only claims a quiet day when no entry qualifies.</p><h2 id="run-the-evals" tabindex="-1">Run the evals <a class="header-anchor" href="#run-the-evals" aria-label="Permalink to &quot;Run the evals&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/codebase-wiki</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/codebase-wiki</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ingest/update-existing</span></span></code></pre></div><p>The cases seed a temp wiki through <code>CODEBASE_WIKI_DIR</code> and build digests with the same formatter the channel uses, so they run without GitHub or network access. The gates check the filesystem, not prose: a new feature page lands on a new slug, a related PR updates the existing page instead of duplicating it, an unmerged PR changes nothing, and the daily pass writes a digest naming both seeded features.</p><h2 id="reuse-the-merge-ingestion-pattern" tabindex="-1">Reuse the merge-ingestion pattern <a class="header-anchor" href="#reuse-the-merge-ingestion-pattern" aria-label="Permalink to &quot;Reuse the merge-ingestion pattern&quot;">​</a></h2><p>Copy this shape when events should accumulate into curated state:</p><ul><li>Acknowledge webhooks with a task and decide host-side whether a model turn is worth spending.</li><li>Seed evidence through <code>workspaceFiles</code> so the model never fetches.</li><li>Constrain the durable store&#39;s shape in code and its content in a skill.</li><li>Add a consolidation schedule so incremental writes stay coherent.</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="./../guides/github.html">GitHub webhooks</a></li><li><a href="./../reference/schedules.html">Schedules</a></li><li><a href="./../reference/tools.html">Tools</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,40)])])}const k=a(n,[["render",d]]);export{g as __pageData,k as default};

package/dist/docs/assets/example-agents_codebase-wiki.md.BBNw9Ekr.lean.js

@@ -1 +0,0 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const g=JSON.parse('{"title":"Build a feature wiki from merged pull requests","description":"Ingest every merged PR into per-feature wiki pages, consolidate with a daily digest schedule, and answer codebase questions with page citations.","frontmatter":{"title":"Build a feature wiki from merged pull requests","description":"Ingest every merged PR into per-feature wiki pages, consolidate with a daily digest schedule, and answer codebase questions with page citations."},"headers":[],"relativePath":"example-agents/codebase-wiki.md","filePath":"example-agents/codebase-wiki.md"}'),n={name:"example-agents/codebase-wiki.md"};function d(o,e,r,l,h,c){return t(),s("div",null,[...e[0]||(e[0]=[i("",40)])])}const k=a(n,[["render",d]]);export{g as __pageData,k as default};

package/dist/docs/assets/example-agents_codeowners-review.md.Bfta-lBU.js

@@ -1,8 +0,0 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.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>
-<span class="line"><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;"> \\</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;pr&quot;:&quot;fixture:multi-area&quot;}&#39;</span></span></code></pre></div><p>The fixture routes to <code>billing</code>, <code>database-migrations</code>, and <code>frontend</code>, attaches <code>people/alice</code> because alice authored it, and returns the full evidence map. Point the same tool at a real PR URL and the routing runs against the live file list. The example table maps a hypothetical <code>src/</code> layout, so most real repositories route to <code>general</code> until you adapt <code>reviews/REVIEWERS</code>.</p><h2 id="review-the-planted-fixture" tabindex="-1">Review the planted fixture <a class="header-anchor" href="#review-the-planted-fixture" aria-label="Permalink to &quot;Review the planted fixture&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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/codeowners-review</span></span></code></pre></div><p>In the playground:</p><blockquote><p>Review fixture:multi-area</p></blockquote><p>The fixture plants one violation per area: float dollar math in <code>src/billing/invoice.ts</code>, a <code>DROP COLUMN</code> plus a non-concurrent index in the migration, and a clickable <code>div</code> without loading states in the UI. The trace shows <code>prepare_review</code>, the evidence reads, four parallel <code>area-reviewer</code> cards, and an aggregated CHANGES REQUESTED verdict with each planted bug filed under its own area. The second fixture, <code>fixture:jobs-clean</code>, routes to <code>background-jobs</code> alone and ends in APPROVE.</p><p>Review a real PR the same way:</p><blockquote><p>Review <a href="https://github.com/owner/repo/pull/123" target="_blank" rel="noreferrer">https://github.com/owner/repo/pull/123</a></p></blockquote><p>Or replay one as a webhook delivery:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/owner/repo/pull/123</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/codeowners-review</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --action</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> opened</span></span></code></pre></div><h2 id="see-how-the-verdict-stays-mechanical" tabindex="-1">See how the verdict stays mechanical <a class="header-anchor" href="#see-how-the-verdict-stays-mechanical" aria-label="Permalink to &quot;See how the verdict stays mechanical&quot;">​</a></h2><p>The reviewer contract computes verdicts from findings instead of letting the model pick a mood: findings first, then <code>request-changes</code> if any High exists or two Mediums do, otherwise <code>approve</code>. Pre-existing issues visible in context are scoped out, at most one advisory Low. The lead applies one rule on top: the PR is APPROVE only when every non-advisory area approved.</p><h2 id="run-the-evals" tabindex="-1">Run the evals <a class="header-anchor" href="#run-the-evals" aria-label="Permalink to &quot;Run the evals&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/codeowners-review</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/codeowners-review</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> review/multi-area</span></span></code></pre></div><p><code>review/multi-area</code> gates the whole pipeline: <code>prepare_review</code> runs, at least three subagent delegations happen, the reply carries every area section plus alice&#39;s advisory notes, the planted billing and migration bugs surface, and the verdict requests changes. <code>review/clean-approve</code> proves the approval path on the clean fixture, and <code>review/routing-question</code> gates that routing answers come from <code>list_review_areas</code>.</p><h2 id="reuse-the-ownership-routing-pattern" tabindex="-1">Reuse the ownership-routing pattern <a class="header-anchor" href="#reuse-the-ownership-routing-pattern" aria-label="Permalink to &quot;Reuse the ownership-routing pattern&quot;">​</a></h2><p>Copy this shape when different code deserves different judgment:</p><ul><li>Route with data and code, not prompt instructions. Tables and globs are testable.</li><li>Write one playbook per domain and keep each reviewer blind to the others.</li><li>Make verdicts mechanical so aggregation is arithmetic, not negotiation.</li><li>Ship fixtures with planted findings so the review quality itself is testable offline.</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="./approval-buddy.html">Approval Buddy</a> for posting real approvals</li><li><a href="./../reference/subagents.html">Subagents</a></li><li><a href="./../guides/github.html">GitHub webhooks</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,43)])])}const g=a(r,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/example-agents_codeowners-review.md.Bfta-lBU.lean.js

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

@@ -1,22 +0,0 @@
-import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.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><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 this package, 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:#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;">TMPDIR</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:-/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">tmp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}/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>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -R</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/concierge/agent</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>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/concierge/package.json</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>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent/agent/{agent.ts,instructions.md,ab.ts,ab.config.ts}</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAIR_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/weather-agent/agent/&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -R</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent/agent/{tools,skills,mcp-connections,subagents,schedules,hooks,lib}</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAIR_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/weather-agent/agent/&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -R</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent/mcp</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/&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/weather-agent/package.json</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/&quot;</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</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;">&quot;</span></span></code></pre></div><p>The host resolves the peer after it knows every mount. The local peer URL is <code>http://127.0.0.1:3000/weather-agent/v1/mcp</code>. You still need an agent-runtime credential for both model turns.</p><h2 id="exercise-delegation" tabindex="-1">Exercise delegation <a class="header-anchor" href="#exercise-delegation" aria-label="Permalink to &quot;Exercise delegation&quot;">​</a></h2><p>Send a weather request to the running Concierge:</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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/concierge</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;What should I pack for Paris tomorrow?&quot;</span></span></code></pre></div><p>Open both playgrounds:</p><ul><li><code>http://127.0.0.1:3000/concierge/playground</code></li><li><code>http://127.0.0.1:3000/weather-agent/playground</code></li></ul><p>The Concierge transcript shows the MCP call. The weather playground shows a separate session on the <code>mcp</code> channel with live weather tool calls.</p><p>Now send a general request:</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;"> chat</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/concierge</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;Give me three ideas for a quiet weekend.&quot;</span></span></code></pre></div><p>The instructions tell Concierge to answer without delegating. This contrast is the proof loop: weather goes to the peer, unrelated work stays local.</p><h2 id="preserve-peer-context" tabindex="-1">Preserve peer context <a class="header-anchor" href="#preserve-peer-context" aria-label="Permalink to &quot;Preserve peer context&quot;">​</a></h2><p><code>weather.ask</code> returns a peer <code>sessionId</code>. Passing it back to a later <code>ask</code> continues the same weather conversation. Concierge&#39;s instructions require this for follow-ups dependent on an earlier answer.</p><p>Use a fresh call when the tasks are independent. Reuse the peer session when the second question needs facts or choices from the first.</p><h2 id="keep-delegation-bounded" tabindex="-1">Keep delegation bounded <a class="header-anchor" href="#keep-delegation-bounded" aria-label="Permalink to &quot;Keep delegation bounded&quot;">​</a></h2><p>The Agent SDK rejects unknown peer slugs and self-references during startup. It doesn&#39;t stop a cycle across several valid peers. If agent A delegates all work to B and B delegates all work to A, they can recurse.</p><p>The prompt provides the guardrail here:</p><ul><li>delegate every weather request,</li><li>include complete context, and</li><li>never delegate unrelated work.</li></ul><p>Write similarly narrow routing rules for each peer. A tool description helps the model choose the connection, but the always-on instructions own the policy.</p><h2 id="use-peers-from-cloud-turns" tabindex="-1">Use peers from cloud turns <a class="header-anchor" href="#use-peers-from-cloud-turns" aria-label="Permalink to &quot;Use peers from cloud turns&quot;">​</a></h2><p>Local turns reach peers over loopback. A cloud VM can&#39;t reach the serve host&#39;s loopback address. Set a public URL when a cloud agent needs the peer:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAIR_DIR</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --public-url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://agents.example.com</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --bearer-token</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>The Agent SDK attaches the bearer token to peer calls. Without <code>--public-url</code>, cloud turns omit peer connections and the server logs a warning.</p><h2 id="compose-your-own-pair" tabindex="-1">Compose your own pair <a class="header-anchor" href="#compose-your-own-pair" aria-label="Permalink to &quot;Compose your own pair&quot;">​</a></h2><p>To compose your own agents:</p><ol><li>Give each project a stable directory slug.</li><li>Add <code>agent/mcp-connections/&lt;name&gt;.ts</code> to the caller.</li><li>Set <code>agent</code> to the target slug.</li><li>Describe the exact work the peer owns.</li><li>Mount both projects from their parent directory.</li><li>Add evals for delegated and non-delegated requests.</li></ol><p>Keep the peer independently useful. If the specialist only makes sense inside one parent and needs no independent sessions, use a subagent instead.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a></li><li><a href="./../reference/connections.html">MCP connections</a></li><li><a href="./../reference/subagents.html">Subagents</a></li><li><a href="./../reference/sessions.html">Sessions and streaming</a></li></ul>`,52)])])}const g=s(n,[["render",l]]);export{k as __pageData,g as default};

package/dist/docs/assets/example-agents_concierge.md.BzB2b20R.lean.js

@@ -1 +0,0 @@
-import{_ as s,c as a,o as i,ag as t}from"./chunks/framework.BCISBCiQ.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_index.md.ChBp0AX6.js

@@ -1,2 +0,0 @@
-import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.BCISBCiQ.js";const m=JSON.parse('{"title":"Choose the right Agent SDK example","description":"Compare the example agents by runtime, channels, tools, state, and the framework pattern each one teaches.","frontmatter":{"title":"Choose the right Agent SDK example","description":"Compare the example agents by runtime, channels, tools, state, and the framework pattern each one teaches."},"headers":[],"relativePath":"example-agents/index.md","filePath":"example-agents/index.md"}'),i={name:"example-agents/index.md"};function n(o,e,d,l,h,c){return r(),a("div",null,[...e[0]||(e[0]=[s(`<h1 id="choose-the-right-agent-sdk-example" tabindex="-1">Choose the right Agent SDK example <a class="header-anchor" href="#choose-the-right-agent-sdk-example" aria-label="Permalink to &quot;Choose the right Agent SDK example&quot;">​</a></h1><p>The examples progress from one-channel assistants to durable, event-driven workflows. Start with the smallest agent for your use case. Each guide explains its request flow, framework features, verification path, and reusable design.</p><p>The source projects live under <a href="./../../examples/"><code>examples/</code></a>. Run the commands below from this package. See <a href="/docs/#run-the-cli">Run the CLI</a> if the <code>agent-sdk</code> command isn&#39;t installed.</p><h2 id="compare-the-examples" tabindex="-1">Compare the examples <a class="header-anchor" href="#compare-the-examples" aria-label="Permalink to &quot;Compare the examples&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Agent</th><th>Runtime</th><th>Intake</th><th>Framework focus</th><th>What sets it apart</th></tr></thead><tbody><tr><td><a href="./weather-agent.html">Weather agent</a></td><td>Cloud</td><td>HTTP and two Slack transports</td><td>Tools, stdio MCP, skill, subagent, schedule, hooks, A/B, and evals</td><td>It demonstrates the broad cloud-runtime surface in one domain.</td></tr><tr><td><a href="./slack-agent.html">Slack agent</a></td><td>Local</td><td>Account-linked Slack</td><td>Channel identity, threads, and suggested prompts</td><td>It reaches Slack without authored tools.</td></tr><tr><td><a href="./concierge.html">Concierge</a></td><td>Local</td><td>Built-in HTTP</td><td>Peer MCP and multi-agent serving</td><td>It delegates to a separate agent with its own tools, sessions, and context.</td></tr><tr><td><a href="./benny.html">Playbook router</a></td><td>Local with repo context</td><td>Two Slack transports</td><td>Channel watching, inherited skills, custom cwd, and an eval</td><td>An allowlisted Slack channel becomes an intake queue for repo playbooks.</td></tr><tr><td><a href="./oncall.html">Alert investigator</a></td><td>Local</td><td>Watched Slack alerts channel</td><td>Bot-post channel watching, per-thread debounce, reminder tools, and host Slack calls</td><td>Every alert gets a thread-pinned investigation that schedules its own re-checks.</td></tr><tr><td><a href="./bugbot.html">PR evidence reviewer</a></td><td>Local</td><td>Custom HTTP and Slack</td><td>Host tool, skill, seeded workspaces, and an eval</td><td>The model receives a prepared diff-first evidence tree instead of a checkout.</td></tr><tr><td><a href="./approval-buddy.html">Approval Buddy</a></td><td>Local</td><td>GitHub and Slack</td><td>Policy tools, two subagents, durable storage, and evals</td><td>Code decides whether a PR may be approved. Reviews stay informational.</td></tr><tr><td><a href="./security-reviewer.html">Security Reviewer</a></td><td>Local host pipeline</td><td>GitHub and chat</td><td>Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals</td><td>Reviewers and triage overlap while the playground shows every stage.</td></tr><tr><td><a href="./knowledge-base.html">Knowledge base</a></td><td>Local</td><td>Built-in HTTP chat</td><td>Durable host-side state, a conventions skill, a schedule, unit tests, and evals</td><td>People curate shared facts in chat, and fresh sessions retrieve them from markdown.</td></tr><tr><td><a href="./codebase-wiki.html">Codebase wiki</a></td><td>Local</td><td>GitHub and chat</td><td>Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals</td><td>Merged PRs accumulate into per-feature wiki pages with a daily digest.</td></tr><tr><td><a href="./codeowners-review.html">Codeowners review</a></td><td>Local</td><td>GitHub, chat, and fixtures</td><td>Ownership routing in code, playbook data files, parallel subagents, and evals</td><td>Each product area reviews with its own playbook, and verdicts aggregate mechanically.</td></tr></tbody></table><h2 id="pick-a-learning-path" tabindex="-1">Pick a learning path <a class="header-anchor" href="#pick-a-learning-path" aria-label="Permalink to &quot;Pick a learning path&quot;">​</a></h2><p>Use this order when you want to learn the Agent SDK one capability at a time:</p><ol><li>Start with <a href="./weather-agent.html">Weather agent</a> to explore the filesystem conventions and cloud runtime.</li><li>Strip the project back to <a href="./slack-agent.html">Slack agent</a> to see the minimum channel surface.</li><li>Read <a href="./benny.html">Playbook router</a> when Slack should route requests into repo playbooks.</li><li>Continue to <a href="./oncall.html">Alert investigator</a> when the intake is bot posts and the agent must pace its own engagement and re-checks.</li><li>Add composition with <a href="./concierge.html">Concierge</a>.</li><li>Study <a href="./bugbot.html">PR evidence reviewer</a> before giving a model repository evidence.</li><li>Move policy into code with <a href="./approval-buddy.html">Approval Buddy</a>.</li><li>Study <a href="./security-reviewer.html">Security Reviewer</a> for host-side PR work.</li><li>See parallel subagent delegation carry team judgment in <a href="./codeowners-review.html">Codeowners review</a>.</li><li>Curate team context through conversation with <a href="./knowledge-base.html">Knowledge base</a>, then let GitHub events maintain product documentation in <a href="./codebase-wiki.html">Codebase wiki</a>.</li></ol><h2 id="common-prerequisites" tabindex="-1">Common prerequisites <a class="header-anchor" href="#common-prerequisites" aria-label="Permalink to &quot;Common prerequisites&quot;">​</a></h2><p>All examples require:</p><ul><li>Node 22.13 or newer. Don&#39;t run the Agent SDK under Bun.</li><li>Workspace dependencies installed.</li><li>An agent-runtime credential for model turns.</li></ul><p>Several examples need more:</p><ul><li>Account-linked Slack channels require a connected host account.</li><li>Alert investigator needs a dedicated Socket Mode app with channel-post events and membership in the watched alerts channel.</li><li>GitHub examples require access to the target repository. Codebase wiki and Codeowners review call the host <code>gh</code> CLI for PR data; the codeowners fixtures run without network.</li><li>Example agents use <code>cursorHostedStorage</code> in <code>agent/storage.ts</code> for hosted session storage. See <a href="./../storage.html">Storage</a>.</li></ul><p>Each guide lists its own credentials, services, and side effects.</p><h2 id="validate-any-example" tabindex="-1">Validate any example <a class="header-anchor" href="#validate-any-example" aria-label="Permalink to &quot;Validate any example&quot;">​</a></h2><p>Discovery commands don&#39;t start a model turn:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 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></code></pre></div><p>Start one development server with <code>agent-sdk dev examples/&lt;name&gt;</code>. Concierge depends on Weather agent, so its guide creates an isolated two-project mount. Don&#39;t mount the whole examples directory to test one agent; several advanced examples subscribe to live GitHub events.</p><h2 id="read-by-framework-feature" tabindex="-1">Read by framework feature <a class="header-anchor" href="#read-by-framework-feature" aria-label="Permalink to &quot;Read by framework feature&quot;">​</a></h2><ul><li><a href="./../concepts.html">Concepts</a> explains filesystem discovery and runtime boundaries.</li><li><a href="./../reference/project-layout.html">Project layout</a> lists every authored folder.</li><li><a href="./../reference/tools.html">Tools</a>, <a href="./../reference/channels.html">channels</a>, and <a href="./../reference/connections.html">MCP connections</a> cover the core extension points.</li><li><a href="./../evals.html">Evals</a> and <a href="./../ab.html">live A/B metrics</a> cover measured iteration.</li><li><a href="./../deployment.html">Deployment</a> covers credentials, auth, storage, and hosting.</li></ul>`,20)])])}const u=t(i,[["render",n]]);export{m as __pageData,u as default};

package/dist/docs/assets/example-agents_index.md.ChBp0AX6.lean.js

@@ -1 +0,0 @@
-import{_ as t,c as a,o as r,ag as s}from"./chunks/framework.BCISBCiQ.js";const m=JSON.parse('{"title":"Choose the right Agent SDK example","description":"Compare the example agents by runtime, channels, tools, state, and the framework pattern each one teaches.","frontmatter":{"title":"Choose the right Agent SDK example","description":"Compare the example agents by runtime, channels, tools, state, and the framework pattern each one teaches."},"headers":[],"relativePath":"example-agents/index.md","filePath":"example-agents/index.md"}'),i={name:"example-agents/index.md"};function n(o,e,d,l,h,c){return r(),a("div",null,[...e[0]||(e[0]=[s("",20)])])}const u=t(i,[["render",n]]);export{m as __pageData,u as default};

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

@@ -1,11 +0,0 @@
-import{_ as a,c as s,o as t,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Build a team knowledge base through conversation","description":"Teach an agent about people, systems, decisions, and preferences; store that knowledge as markdown and retrieve it in fresh sessions.","frontmatter":{"title":"Build a team knowledge base through conversation","description":"Teach an agent about people, systems, decisions, and preferences; store that knowledge as markdown and retrieve it in fresh sessions."},"headers":[],"relativePath":"example-agents/knowledge-base.md","filePath":"example-agents/knowledge-base.md"}'),n={name:"example-agents/knowledge-base.md"};function l(o,e,d,r,h,p){return t(),s("div",null,[...e[0]||(e[0]=[i(`<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 a wiki directory on the serve host 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 local 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, or A/B experiment. The wiki directory is the durable knowledge store.</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>
-<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;"> wiki_search</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;query&quot;:&quot;6432&quot;}&#39;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> wiki_read</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;"> --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{}&#39;</span></span></code></pre></div><p>Invalid page ids fail fast. Try <code>{&quot;page&quot;:&quot;../escape&quot;}</code> and the tool returns the validation error instead of touching the filesystem.</p><h2 id="prove-recall-across-sessions" tabindex="-1">Prove recall across sessions <a class="header-anchor" href="#prove-recall-across-sessions" aria-label="Permalink to &quot;Prove recall across sessions&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;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/knowledge-base</span></span></code></pre></div><p>Teach it something in the playground:</p><blockquote><p>Remember: our staging database is Postgres at staging-db.internal.example.com, port 6432 via PgBouncer. Jane Doe owns it.</p></blockquote><p>The trace shows the conventions skill load, then <code>wiki_write</code> calls for <code>staging-database</code>, <code>people/jane-doe</code>, and <code>index</code>. Start a new session and ask:</p><blockquote><p>What port does our staging database use, and who owns it?</p></blockquote><p>The fresh session finds the answer with <code>wiki_search</code> and <code>wiki_read</code> and cites the pages. The conversation history is empty; the wiki is the source of truth.</p><h2 id="run-the-gardener" tabindex="-1">Run the gardener <a class="header-anchor" href="#run-the-gardener" aria-label="Permalink to &quot;Run the gardener&quot;">​</a></h2><p>The <code>gardener</code> schedule fires at 06:00 UTC and rewrites the wiki for consistency: merge near-duplicate pages, rebuild <code>index</code>, and flag facts older than 90 days. Under <code>agent-sdk dev</code>, timers don&#39;t auto-fire. Trigger it by hand:</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:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/knowledge-base/v1/dev/schedules/gardener</span></span></code></pre></div><h2 id="run-the-evals" tabindex="-1">Run the evals <a class="header-anchor" href="#run-the-evals" aria-label="Permalink to &quot;Run the evals&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> examples/knowledge-base</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/knowledge-base</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> knowledge/recall</span></span></code></pre></div><p>The eval file seeds a temp directory through <code>KNOWLEDGE_BASE_DIR</code> inside the cases, so the durable knowledge base never sees test data. <code>knowledge/recall</code> proves the fact comes from disk, not the conversation. <code>knowledge/save</code> gates the write decision, and <code>knowledge/no-write-on-ephemera</code> proves small talk stays out of the knowledge base.</p><h2 id="reuse-the-knowledge-base-pattern" tabindex="-1">Reuse the knowledge-base pattern <a class="header-anchor" href="#reuse-the-knowledge-base-pattern" aria-label="Permalink to &quot;Reuse the knowledge-base pattern&quot;">​</a></h2><p>Copy this shape when an agent needs durable, inspectable team knowledge:</p><ul><li>Resolve the storage root lazily behind an environment override.</li><li>Validate identifiers in the store, not in the prompt.</li><li>Put naming and structure conventions in a skill so writes stay consistent.</li><li>Add a consolidation schedule instead of letting pages rot.</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/skills.html">Skills</a></li><li><a href="./../reference/schedules.html">Schedules</a></li><li><a href="./../evals.html">Evals</a></li></ul>`,43)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};