@cursor/july 0.1.111 → 0.1.112

package/dist/docs/assets/reference_evals.md.DNJzM_yf.js

@@ -0,0 +1,57 @@
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Evals","description":"Reference for eval discovery, cases, assertions, judges, configuration, fixtures, reporters, and runner output.","frontmatter":{"title":"Evals","description":"Reference for eval discovery, cases, assertions, judges, configuration, fixtures, reporters, and runner output."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function d(l,s,h,r,p,o){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="evals-reference" tabindex="-1">Evals reference <a class="header-anchor" href="#evals-reference" aria-label="Permalink to &quot;Evals reference&quot;">​</a></h1><p>This page is the complete authoring and runner contract for <code>@cursor/july/evals</code>. Start with the <a href="./../evals.html">Evals guide</a> for the workflow and first regression case.</p><h2 id="discovery-and-case-ids" tabindex="-1">Discovery and case IDs <a class="header-anchor" href="#discovery-and-case-ids" aria-label="Permalink to &quot;Discovery and case IDs&quot;">​</a></h2><p>Eval files live under the project-root <code>evals/</code> directory and end in <code>.eval.ts</code> or <code>.eval.js</code>. The path under that directory becomes the eval ID:</p><ul><li><code>evals/readiness.eval.ts</code> becomes <code>readiness</code>.</li><li><code>evals/builds/api.eval.ts</code> becomes <code>builds/api</code>.</li><li><code>evals/builds/index.eval.ts</code> becomes <code>builds</code>.</li></ul><p>Export one <code>defineEval</code> with either <code>test</code> or <code>cases</code>, not both. A case ID appends one path segment to the file ID:</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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smoke&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cases: [</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;checkout&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review checkout PR 42.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review search PR 7.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Those cases are <code>prs/checkout</code> and <code>prs/search</code> when the file is <code>evals/prs.eval.ts</code>. Case IDs must be unique single path segments.</p><p>A file can also export an array of <code>defineEval</code> calls. The runner names them with zero-padded indexes such as <code>sql/0000</code>. Use named <code>cases</code> for handwritten scenarios and arrays for loaded datasets.</p><p><code>iterations</code> repeats one datapoint from 1 to 100 times. For <code>iterations: 3</code>, <code>weather/nyc</code> expands to <code>weather/nyc/1</code>, <code>weather/nyc/2</code>, and <code>weather/nyc/3</code>; selecting <code>weather/nyc</code> runs all three.</p><h2 id="configuration" tabindex="-1">Configuration <a class="header-anchor" href="#configuration" aria-label="Permalink to &quot;Configuration&quot;">​</a></h2><p>Every running suite needs <code>evals/evals.config.ts</code> with <code>maxConcurrency</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEvalConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineEvalConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  maxConcurrency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  timeoutMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">180_000</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  judge: { model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;gpt-5.4-mini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>maxConcurrency</code></td><td>Required; concurrent authored datapoints, from 1 to 200</td></tr><tr><td><code>timeoutMs</code></td><td>Per-case timeout; case/file, CLI, then config precedence</td></tr><tr><td><code>judge</code></td><td>Default model for <code>t.judge</code></td></tr><tr><td><code>reporters</code></td><td>Objects notified as cases and runs complete</td></tr><tr><td><code>maxPlaygroundRuns</code></td><td>Number of server-side batches kept in playground history</td></tr></tbody></table><p>A case can override <code>description</code>, <code>tags</code>, <code>timeoutMs</code>, <code>iterations</code>, <code>judge</code>, <code>reporters</code>, and <code>metadata</code>. Case metadata merges over file-level metadata; case reporters add to the file&#39;s reporters.</p><h2 id="drive-turns-with-t-send" tabindex="-1">Drive turns with <code>t.send</code> <a class="header-anchor" href="#drive-turns-with-t-send" aria-label="Permalink to &quot;Drive turns with \`t.send\`&quot;">​</a></h2><p><code>await t.send(message, options?)</code> runs one turn and waits until it finishes, fails, or parks for approval. Several sends in one test share the session.</p><p>The returned turn exposes its assistant <code>message</code>, <code>sessionId</code>, <code>events</code>, ordered <code>toolCalls</code>, <code>ok</code>, and turn <code>index</code>. Assertions on the turn inspect only that turn; assertions on <code>t</code> inspect the whole run. Useful run values include <code>t.reply</code>, <code>t.events</code>, <code>t.turns</code>, <code>t.sessionId</code>, and the timeout <code>t.signal</code>.</p><p>These options apply on the first send because they shape the session:</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>workspaceFiles</code></td><td>Relative path-to-content map seeded into the session workspace</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute local harness working directory</td></tr><tr><td><code>cloud</code></td><td>Cloud session options merged over the agent&#39;s static cloud config</td></tr></tbody></table><p>Use <code>turn.expectOk()</code> when later test steps depend on that turn succeeding.</p><h2 id="trajectory-assertions" tabindex="-1">Trajectory assertions <a class="header-anchor" href="#trajectory-assertions" aria-label="Permalink to &quot;Trajectory assertions&quot;">​</a></h2><p>Assertions record failures and let the test continue, so one case reports every violated contract.</p><table tabindex="0"><thead><tr><th>Assertion</th><th>Checks</th></tr></thead><tbody><tr><td><code>t.succeeded()</code></td><td>Run finished without failure or an unanswered approval</td></tr><tr><td><code>t.parked()</code></td><td>Run stopped on an unanswered approval</td></tr><tr><td><code>t.calledTool(name, matcher?)</code></td><td>Matching tool request occurred</td></tr><tr><td><code>t.notCalledTool(name)</code></td><td>No request for that tool occurred</td></tr><tr><td><code>t.loadedSkill(name)</code></td><td>Agent opened a named skill</td></tr><tr><td><code>t.toolOrder(names)</code></td><td>Tool requests appeared in relative order</td></tr><tr><td><code>t.usedNoTools()</code></td><td>No tool was requested</td></tr><tr><td><code>t.maxToolCalls(max)</code></td><td>Tool-call count stayed under the bound</td></tr><tr><td><code>t.noFailedActions()</code></td><td>No tool result failed</td></tr><tr><td><code>t.calledSubagent(name, matcher?)</code></td><td>Matching subagent call occurred</td></tr><tr><td><code>t.taggedArtifact(kind?, predicate?)</code></td><td>Matching durable artifact was tagged</td></tr><tr><td><code>t.event(type, matcher?)</code></td><td>Matching session event occurred</td></tr><tr><td><code>t.notEvent(type, matcher?)</code></td><td>Matching session event did not occur</td></tr><tr><td><code>t.eventOrder(matchers)</code></td><td>Event groups appeared in relative order</td></tr><tr><td><code>t.eventsSatisfy(label, predicate)</code></td><td>Predicate accepted the event stream</td></tr><tr><td><code>t.check(value, expectation)</code></td><td>Value met an expectation builder</td></tr><tr><td><code>t.score(name, value)</code></td><td>Recorded a numeric score from 0 to 1</td></tr></tbody></table><p><code>t.requireToolCall</code>, <code>t.requireInputRequest</code>, and <code>t.require</code> return the matched value and stop the remaining test body when no match exists.</p><h2 id="tool-and-event-matchers" tabindex="-1">Tool and event matchers <a class="header-anchor" href="#tool-and-event-matchers" aria-label="Permalink to &quot;Tool and event matchers&quot;">​</a></h2><p>Tool matchers can narrow by <code>input</code>, <code>output</code>, <code>status</code>, and <code>count</code>. Values accept literals, regular expressions, or predicates. Object literals partial-deep-match:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  input: { verdict: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  status: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;completed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  count: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</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>Tool status is <code>completed</code>, <code>failed</code>, <code>pending</code>, or <code>rejected</code>. Subagent matchers accept <code>output</code>, <code>status</code>, <code>count</code>, and <code>callId</code>. Event matchers accept <code>data</code> and <code>count</code>.</p><h2 id="expectation-builders" tabindex="-1">Expectation builders <a class="header-anchor" href="#expectation-builders" aria-label="Permalink to &quot;Expectation builders&quot;">​</a></h2><p>Import builders from <code>@cursor/july/evals</code>:</p><table tabindex="0"><thead><tr><th>Builder</th><th>Default severity</th></tr></thead><tbody><tr><td>\`includes(string</td><td>RegExp)\`</td></tr><tr><td><code>equals(value)</code></td><td>Hard gate</td></tr><tr><td><code>matches(schema)</code></td><td>Hard gate</td></tr><tr><td><code>satisfies(predicate, label)</code></td><td>Hard gate</td></tr><tr><td><code>similarity(expected)</code></td><td>Soft score</td></tr></tbody></table><p><code>matches</code> accepts Standard Schema implementations such as Zod. <code>normalizedSimilarity(value, expected)</code> returns the same 0-to-1 value used by <code>similarity</code>.</p><h2 id="severity-and-verdicts" tabindex="-1">Severity and verdicts <a class="header-anchor" href="#severity-and-verdicts" aria-label="Permalink to &quot;Severity and verdicts&quot;">​</a></h2><p>Every assertion returns a severity handle:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;search&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">soft</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">similarity</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Expected answer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">closedQA</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;names the failing step&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><ul><li><code>.gate(threshold?)</code> fails the case when it misses.</li><li><code>.soft(threshold?)</code> records a value without failing.</li><li><code>.atLeast(threshold)</code> records a soft bar; a miss produces a <code>scored</code> verdict.</li></ul><p>Case verdicts are <code>passed</code>, <code>failed</code>, <code>scored</code>, or <code>skipped</code>. The CLI exits 1 for a failed gate. A scored result exits 0 unless <code>--strict</code> is set. Exit 2 means the selection matched no cases.</p><h2 id="judges" tabindex="-1">Judges <a class="header-anchor" href="#judges" aria-label="Permalink to &quot;Judges&quot;">​</a></h2><p>Use a judge for meaning that deterministic checks cannot express:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">factuality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">summarizes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">closedQA</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;names the root cause&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">gate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.judge.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sql</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(expected).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.9</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Each grades <code>t.reply</code> by default; pass <code>{ on }</code> to grade another value. Judge configuration can live in the project config, eval, case, or call, with the nearest value winning.</p><p><code>t.judge.model(prompt)</code> returns a raw model reply for custom grading. Treat agent output as untrusted input: wrap it with <code>fenceUntrusted</code> and include <code>EVAL_JUDGE_INJECTION_GUARD</code> in the judge prompt.</p><h2 id="datasets-and-fixtures" tabindex="-1">Datasets and fixtures <a class="header-anchor" href="#datasets-and-fixtures" aria-label="Permalink to &quot;Datasets and fixtures&quot;">​</a></h2><p>Load committed JSON, JSONL, or YAML relative to the project root:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEval, includes } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { loadYaml } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/evals/loaders&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> rows</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> loadYaml</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  Array</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{ </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string; </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string; </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">expected</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: string }</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;evals/data/cases.yaml&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> rows.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">map</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">row</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    description: row.task,</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(row.prompt);</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(row.expected));</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  })</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Materialize API-backed evidence before running a large suite. Commit the exact payload, diff, or metadata revision and seed it with <code>workspaceFiles</code>.</p><h2 id="reporters-and-results" tabindex="-1">Reporters and results <a class="header-anchor" href="#reporters-and-results" aria-label="Permalink to &quot;Reporters and results&quot;">​</a></h2><p>Built-in reporters include <code>JUnit({ filePath, suiteName? })</code> and <code>Artifacts({ dir })</code>. Custom reporters can expose <code>onRunStart</code>, <code>onEvalComplete</code>, and <code>onRunComplete</code>. Reporter errors are logged and do not change the eval verdict.</p><p>JSON output contains run totals plus one result per case. A result can include the case ID, verdict, assertions, session ID, inputs, tool calls, metrics, logs, duration, metadata, tags, final text, and error or skip details.</p><h2 id="cli-selection-and-artifacts" tabindex="-1">CLI selection and artifacts <a class="header-anchor" href="#cli-selection-and-artifacts" aria-label="Permalink to &quot;CLI selection and artifacts&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;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> builds/checkout</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --verbose</span></span></code></pre></div><p>ID filters match an exact ID and its descendants. Repeated IDs use OR; repeated tags use OR. When both are present, a case must match both groups.</p><p>The local runner starts an ephemeral server. Default artifacts go under <code>evals/&lt;stamp&gt;/</code> in the project state directory and include <code>summary.json</code>, <code>results.jsonl</code>, and <code>evals/&lt;case-id&gt;.json</code>. <code>--artifacts &lt;dir&gt;</code> chooses another destination; <code>--no-artifacts</code> disables them. This location is independent of <code>--state-root</code>.</p><p>Model and judge turns resolve credentials in this order: <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>agent-sdk login</code>. Listing cases needs no credential.</p><h2 id="playground-and-hosted-runs" tabindex="-1">Playground and hosted runs <a class="header-anchor" href="#playground-and-hosted-runs" aria-label="Permalink to &quot;Playground and hosted runs&quot;">​</a></h2><p>The playground <strong>Evals</strong> view starts batches on its running server and keeps their sessions in the normal session list. <code>--url</code> targets a named running server; <code>--prod --slug &lt;slug&gt;</code> targets a hosted deployment.</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;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vulnerability-scanner</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tag</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> smoke</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:#032F62;--shiki-dark:#9ECBFF;"> status</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">eval-i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vulnerability-scanner</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:#032F62;--shiki-dark:#9ECBFF;"> cancel</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">eval-i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vulnerability-scanner</span></span></code></pre></div><p>Server-side batches use the target server&#39;s discovered evals and store results in its playground history. Local-only reporter and concurrency flags do not apply to <code>--url</code> or <code>--prod</code> runs.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../evals.html">Evals guide</a>: author and run a regression workflow</li><li><a href="./cli.html#eval">CLI reference</a>: every runner flag</li><li><a href="./sessions.html">Sessions</a>: event vocabulary used by trajectory checks</li><li><a href="./artifacts.html">Artifacts</a>: durable outputs asserted by <code>taggedArtifact</code></li></ul>`,61)])])}const E=i(n,[["render",d]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_evals.md.DNJzM_yf.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Evals","description":"Reference for eval discovery, cases, assertions, judges, configuration, fixtures, reporters, and runner output.","frontmatter":{"title":"Evals","description":"Reference for eval discovery, cases, assertions, judges, configuration, fixtures, reporters, and runner output."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function d(l,s,h,r,p,o){return e(),a("div",null,[...s[0]||(s[0]=[t("",61)])])}const E=i(n,[["render",d]]);export{c as __pageData,E as default};

package/dist/docs/assets/reference_extensions.md.Ceq-qT8d.js

@@ -0,0 +1,58 @@
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(p,s,o,h,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="extensions" tabindex="-1">Extensions <a class="header-anchor" href="#extensions" aria-label="Permalink to &quot;Extensions&quot;">​</a></h1><p>An extension packages capabilities that would otherwise live under <code>agent/</code>: tools, skills, instructions, connections, hooks, channels, schedules, subagents, artifacts, and workspace seeds. One mount file adds them under a namespace without copying their source into your project.</p><p>Extensions and Cursor plugins execute as trusted host code. A namespace prevents name collisions; it does not sandbox the package or limit its side effects. Review the package before mounting it.</p><h2 id="mount-an-extension" tabindex="-1">Mount an extension <a class="header-anchor" href="#mount-an-extension" aria-label="Permalink to &quot;Mount an extension&quot;">​</a></h2><p>Install the package and add one file under <code>agent/extensions/</code>. The filename becomes the namespace, so this mount contributes names such as <code>ci__failed_jobs</code> and <code>ci__triage</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/ci.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ci </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@acme/ci-triage&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ci</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  org: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  token: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">BUILDKITE_TOKEN</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 extension validates its configuration while the project loads. Missing or mistyped settings fail <code>agent-sdk validate</code> before a turn can call the contributed code.</p><p>Extension instructions are appended to the agent&#39;s prompt. The root agent still needs its own <code>agent/instructions.md</code>.</p><h2 id="see-what-the-extension-added" tabindex="-1">See what the extension added <a class="header-anchor" href="#see-what-the-extension-added" aria-label="Permalink to &quot;See what the extension added&quot;">​</a></h2><p>Run discovery after mounting or upgrading an extension:</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;"> .</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;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p><code>info</code> lists each mount and its namespaced tools, skills, connections, hooks, channels, schedules, subagents, and artifact kinds. The same data appears under <code>extensions</code> in <code>GET /v1/info</code>.</p><p>Names inside the extension stay short. A tool authored as <code>tools/failed_jobs.ts</code> appears to the mounting agent as <code>&lt;namespace&gt;__failed_jobs</code>. The <code>__</code> separator is reserved, so root contributions cannot impersonate a mounted one.</p><h2 id="adjust-a-mounted-extension" tabindex="-1">Adjust a mounted extension <a class="header-anchor" href="#adjust-a-mounted-extension" aria-label="Permalink to &quot;Adjust a mounted extension&quot;">​</a></h2><p>Mount as a directory when you need to replace or remove one contribution. Keep the package mount in <code>extension.ts</code>, then overlay the extension&#39;s short name beneath it.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent/extensions/ci/</span></span>
+<span class="line"><span>  extension.ts</span></span>
+<span class="line"><span>  tools/</span></span>
+<span class="line"><span>    job_log.ts</span></span>
+<span class="line"><span>    retry_job.ts</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/ci/tools/job_log.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  jobLogInput,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  readRedactedLog,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../../../lib/ci.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</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 style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Read a redacted CI log.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: jobLogInput,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  execute: readRedactedLog,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/ci/tools/retry_job.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { disableTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> disableTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>The first file replaces <code>ci__job_log</code>; the second removes <code>ci__retry_job</code>. Use the matching <code>disable*</code> helper for another slot, or generic <code>disable()</code> when the file location already identifies it. Validation fails when an overlay names a contribution the package does not provide.</p><h2 id="mount-a-cursor-plugin" tabindex="-1">Mount a Cursor plugin <a class="header-anchor" href="#mount-a-cursor-plugin" aria-label="Permalink to &quot;Mount a Cursor plugin&quot;">​</a></h2><p><code>cursorPlugin()</code> adapts a vendored Cursor or Claude plugin into the same namespace model. Skills, commands, agents, and MCP servers become Agent SDK skills, subagents, and connections.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/extensions/notion.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { cursorPlugin } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> cursorPlugin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;plugins/notion-workspace&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  variables: {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    NOTION_TOKEN: process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">NOTION_TOKEN</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>path</code> is relative to the project root. <code>variables</code> fills placeholders declared by the plugin&#39;s MCP configuration; unresolved placeholders fail validation instead of mounting a partial server.</p><p>Plugin rules and hooks are not mounted. Overlay a generated <code>mcp-connections/&lt;server&gt;.ts</code> file to replace or disable one plugin server. OAuth-backed plugin servers use <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>; transport and tool-filter details live in <a href="./connections.html">MCP connections</a>.</p><h2 id="what-an-extension-can-contain" tabindex="-1">What an extension can contain <a class="header-anchor" href="#what-an-extension-can-contain" aria-label="Permalink to &quot;What an extension can contain&quot;">​</a></h2><p>Share capabilities that can safely join another agent under a namespace:</p><ul><li>Instructions, tools, skills, MCP and host connections</li><li>Hooks, channels, schedules, and subagents</li><li>Artifact kinds and local workspace seed files</li></ul><p>Agent-wide configuration does not compose through a mount. <code>agent.ts</code>, storage, OpenTelemetry, playground code, custom sandbox backends, and nested extensions are ignored in an extension package; <code>agent-sdk validate</code> reports unsupported paths.</p><h2 id="build-an-extension" tabindex="-1">Build an extension <a class="header-anchor" href="#build-an-extension" aria-label="Permalink to &quot;Build an extension&quot;">​</a></h2><p>Lay out the package like the shareable part of <code>agent/</code>. The root <code>extension.ts</code> supplies a description and validates any settings the consumer must provide.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>@acme/ci-triage/</span></span>
+<span class="line"><span>  package.json</span></span>
+<span class="line"><span>  extension.ts</span></span>
+<span class="line"><span>  instructions.md</span></span>
+<span class="line"><span>  tools/</span></span>
+<span class="line"><span>    failed_jobs.ts</span></span>
+<span class="line"><span>    job_log.ts</span></span>
+<span class="line"><span>  skills/</span></span>
+<span class="line"><span>    triage.md</span></span>
+<span class="line"><span>  hooks/</span></span>
+<span class="line"><span>    audit.ts</span></span>
+<span class="line"><span>  lib/</span></span>
+<span class="line"><span>    buildkite.ts</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// extension.ts</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineExtension } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/extensions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineExtension</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  root: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">meta</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.dirname,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Investigate failing Buildkite jobs.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  config: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    org: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    token: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    logTailLines: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">int</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">positive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">200</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Modules inside the package import this definition and read <code>extension.config</code>, which is already validated and has defaults applied. Publish the built entry point with its slot directories and prose assets beside it.</p><p>The <a href="./project-layout.html">Project layout</a> owns each contribution&#39;s authoring contract. Keep extension instructions and tool descriptions namespace-neutral because the consumer chooses the final prefix.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/cloud-agents.html">Cloud agents</a>: delegate repository work through an extension</li><li><a href="./../guides/grokbot-agents.html">Grok Bot agents</a>: consult named bots</li><li><a href="./../guides/improve.html">Self-improvement</a>: propose source changes through pull requests</li><li><a href="./project-layout.html">Project layout</a>: contribution slots</li><li><a href="./tools.html">Tools</a> and <a href="./skills.html">Skills</a>: capability contracts</li></ul>`,36)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/reference_extensions.md.Ceq-qT8d.lean.js

@@ -0,0 +1 @@
+import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds.","frontmatter":{"title":"Extensions","description":"Mount a namespaced package of tools, skills, connections, and other agent capabilities, then inspect or override what it adds."},"headers":[],"relativePath":"reference/extensions.md","filePath":"reference/extensions.md"}'),t={name:"reference/extensions.md"};function l(p,s,o,h,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",36)])])}const g=i(t,[["render",l]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_hooks.md.CZuynAxj.js → reference_hooks.md.B7uzNENk.js}

@@ -1,4 +1,4 @@
-import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function h(o,s,l,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook subscribes to the session event stream and runs a side effect after each event is recorded: an audit line, a metric, a copy of the transcript in your own store, or derived state for later turns. Hooks run in the serving process for every session of the agent, on local and cloud runtime turns alike.</p><p>Hooks observe. They can&#39;t change the turn, the prompt, or the reply, and a handler that throws is logged and skipped. Treat the event as read-only; later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong tool for anything that must happen before the model runs or must fail a turn; see <a href="#when-not-to-use-a-hook">When not to use a hook</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>agent/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/july/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/hooks/usage.ts</span></span>
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function h(o,s,l,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to &quot;Hooks&quot;">​</a></h1><p>A hook subscribes to the session event stream and runs a side effect after each event is recorded: an audit line, a metric, a copy of the transcript in your own store, or derived state for later turns. Hooks run in the serving process for every session of the agent, on local and cloud runtime turns alike.</p><p>Hooks observe. They can&#39;t change the turn, the prompt, or the reply, and a handler that throws is logged and skipped. Treat the event as read-only; later subscribers see the same object. That makes hooks safe to add to a production agent, and the wrong tool for anything that must happen before the model runs or must fail a turn; see <a href="#when-not-to-use-a-hook">When not to use a hook</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to &quot;Author a hook&quot;">​</a></h2><p>Author <code>agent/hooks/&lt;name&gt;.ts</code> with <code>defineHook</code> from <code>@cursor/july/hooks</code>. This one meters tokens:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/hooks/usage.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/hooks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
@@ -15,7 +15,7 @@ import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      ctx.host.otel.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">increment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme.turn.failed&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { channel: ctx.channel.id });</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    },</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>agent/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>agent/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>agent-sdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>agent-sdk init</code> scaffolds <code>agent/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/july/memory</code> and journals every turn for later sessions to read. Delete the file to opt out.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events.</p><p>The payloads hooks read most often:</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message }</code></td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args? }] }</code>. A call with <code>parentCallId</code> belongs to a subagent</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed? }</code>. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/july</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="when-hooks-run" tabindex="-1">When hooks run <a class="header-anchor" href="#when-hooks-run" aria-label="Permalink to &quot;When hooks run&quot;">​</a></h2><p>A hook runs after the event is durably recorded. It never delays the model turn and never sees an event that wasn&#39;t recorded.</p><p>Within one session, events dispatch in order, one at a time: the channel&#39;s <code>events</code> handlers first, then each hook in discovery order. Sessions don&#39;t wait on each other.</p><p>Two consequences:</p><ul><li>A slow handler holds up the next event&#39;s handlers for that session, not the model. Keep handlers short and queue anything slow.</li><li>Hooks fire for eval sessions too. Check <code>ctx.session.purpose === &quot;eval&quot;</code> before metering or paging.</li></ul><p>Each event reaches a hook at most once. A restart doesn&#39;t replay the log into hooks, so a mirror needs no dedupe, and the event log rather than the hook&#39;s copy is the source of truth.</p><h2 id="hooks-channel-events-or-evals" tabindex="-1">Hooks, channel events, or evals? <a class="header-anchor" href="#hooks-channel-events-or-evals" aria-label="Permalink to &quot;Hooks, channel events, or evals?&quot;">​</a></h2><p>All of them consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>agent/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="when-not-to-use-a-hook" tabindex="-1">When not to use a hook <a class="header-anchor" href="#when-not-to-use-a-hook" aria-label="Permalink to &quot;When not to use a hook&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see <a href="./../guides/github.html#show-pr-progress">Show PR progress</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Usage metering is the <a href="#author-a-hook">authoring example</a>. Three more:</p><h3 id="alert-on-failure" tabindex="-1">Alert on failure <a class="header-anchor" href="#alert-on-failure" aria-label="Permalink to &quot;Alert on failure&quot;">​</a></h3><p><code>turn.failed</code> carries the message, and <code>ctx.session.id</code> points at the trace. Skip interrupted turns; those are preemptions, not failures. Read secrets inside the handler: hosted deployments bind them after the process starts, so a module-scope read stays empty. Give the call a timeout, since a stalled request holds up later handlers on that session.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/hooks/page-on-failure.ts</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>agent/hooks/</code>, subfolders included, is a hook named by its path without the extension: <code>agent/hooks/audit/usage.ts</code> is <code>audit/usage</code>. <code>*.test.ts</code> and <code>*.spec.ts</code> files are skipped. The default export must be <code>defineHook(...)</code>, names can&#39;t contain <code>__</code>, and an empty <code>events</code> map skips the hook with a warning; <code>agent-sdk validate</code> reports all three. An extension mounts its hooks as <code>&lt;ns&gt;__&lt;name&gt;</code>, and <code>disableHook()</code> removes one (<a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>).</p><p><code>agent-sdk init</code> scaffolds <code>agent/hooks/memory.ts</code>, which exports <code>memoryHook()</code> from <code>@cursor/july/memory</code> and journals every turn for later sessions to read. Delete the file to opt out.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to &quot;Events and payloads&quot;">​</a></h2><p>Keys are event types from the <a href="./sessions.html#which-events-can-i-stream">event vocabulary</a>, or <code>&quot;*&quot;</code> for every event. A typed key narrows <code>event.data</code>; a <code>&quot;*&quot;</code> handler receives the union, so switch on <code>event.type</code>. Every event carries the stream envelope <code>{ type, index, sessionId, turnId?, at, data }</code>, with <code>turnId</code> set on turn-scoped events.</p><p>The payloads hooks read most often:</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message }</code></td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args? }] }</code>. A call with <code>parentCallId</code> belongs to a subagent</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed? }</code>. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@cursor/july</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to &quot;Handler context&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can&#39;t take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent; the storage backend decides whether it survives a hosted replace. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: &quot;deployment&quot; }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.otel</code></td><td>Counters, histograms, and tags, attributed to this session</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html">reminders</a>, the same API tools get</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="when-hooks-run" tabindex="-1">When hooks run <a class="header-anchor" href="#when-hooks-run" aria-label="Permalink to &quot;When hooks run&quot;">​</a></h2><p>A hook runs after the event is durably recorded. It never delays the model turn and never sees an event that wasn&#39;t recorded.</p><p>Within one session, events dispatch in order, one at a time: the channel&#39;s <code>events</code> handlers first, then each hook in discovery order. Sessions don&#39;t wait on each other.</p><p>Two consequences:</p><ul><li>A slow handler holds up the next event&#39;s handlers for that session, not the model. Keep handlers short and queue anything slow.</li><li>Hooks fire for eval sessions too. Check <code>ctx.session.purpose === &quot;eval&quot;</code> before metering or paging.</li></ul><p>Each event reaches a hook at most once. A restart doesn&#39;t replay the log into hooks, so a mirror needs no dedupe, and the event log rather than the hook&#39;s copy is the source of truth.</p><h2 id="hooks-channel-events-or-evals" tabindex="-1">Hooks, channel events, or evals? <a class="header-anchor" href="#hooks-channel-events-or-evals" aria-label="Permalink to &quot;Hooks, channel events, or evals?&quot;">​</a></h2><p>All of them consume the same stream, for different jobs:</p><table tabindex="0"><thead><tr><th></th><th>Hooks</th><th>Channel <code>events</code></th><th>Evals</th></tr></thead><tbody><tr><td>Scope</td><td>every session of the agent</td><td>sessions the channel owns</td><td>one test turn</td></tr><tr><td>Job</td><td>observe: audit, metrics, mirrors, derived state</td><td>deliver: replies back to the channel&#39;s surface</td><td>assert: gates over the trajectory</td></tr><tr><td>Context</td><td><code>ctx.host</code>, <code>ctx.artifacts</code>, session info</td><td><code>channel.state</code>, <code>setContinuationToken</code>, <code>ctx.host</code>, session info</td><td>the <code>t</code> assertion helpers</td></tr><tr><td>Can affect the run</td><td>no</td><td>yes, it owns the surface</td><td>n/a</td></tr><tr><td>Authored at</td><td><code>agent/hooks/*.ts</code></td><td>channel config</td><td><code>evals/**/*.eval.ts</code></td></tr></tbody></table><h2 id="when-not-to-use-a-hook" tabindex="-1">When not to use a hook <a class="header-anchor" href="#when-not-to-use-a-hook" aria-label="Permalink to &quot;When not to use a hook&quot;">​</a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel&#39;s <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel&#39;s <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>; see the <a href="./../templates/pr-autofixer.html">PR autofixer</a></td></tr><tr><td>Block, approve, or rewrite a tool call</td><td><a href="./tools.html#gate-a-tool-on-human-approval"><code>needsApproval</code></a> on the tool</td></tr><tr><td>Act on the final assistant text, reject it for a same-turn repair, or fail a bad turn</td><td><code>defineResult</code></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Usage metering is the <a href="#author-a-hook">authoring example</a>. Three more:</p><h3 id="alert-on-failure" tabindex="-1">Alert on failure <a class="header-anchor" href="#alert-on-failure" aria-label="Permalink to &quot;Alert on failure&quot;">​</a></h3><p><code>turn.failed</code> carries the message, and <code>ctx.session.id</code> points at the trace. Skip interrupted turns; those are preemptions, not failures. Read secrets inside the handler: hosted deployments bind them after the process starts, so a module-scope read stays empty. Give the call a timeout, since a stalled request holds up later handlers on that session.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/hooks/page-on-failure.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/hooks&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{reference_hooks.md.CZuynAxj.lean.js → reference_hooks.md.B7uzNENk.lean.js}

@@ -1 +1 @@
-import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function h(o,s,l,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t("",45)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};
+import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state.","frontmatter":{"title":"Hooks","description":"Observe-only subscribers to the session event stream: audit logs, metrics, transcript mirrors, derived state."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function h(o,s,l,d,r,p){return i(),a("div",null,[...s[0]||(s[0]=[t("",45)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_http-api.md.DTKcYE6L.js → reference_http-api.md.CduHavZ2.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as s,o,a3 as a}from"./chunks/framework.dypDpWZ3.js";const p=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,c,h){return o(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="http-api-reference" tabindex="-1">HTTP API reference <a class="header-anchor" href="#http-api-reference" aria-label="Permalink to &quot;HTTP API reference&quot;">​</a></h1><p>Agent SDK hosts expose the same public HTTP surface. In the default multi-agent layout each agent is namespaced under its slug (<code>/&lt;slug&gt;/v1/session</code>, <code>/&lt;slug&gt;/playground</code>), with host-level routes at the root. With <code>--mode single</code>, one agent serves the same surface unslugged (<code>/v1/*</code>).</p><p>Unless noted otherwise, routes run the agent&#39;s HTTP auth chain: the default is <code>localDevStrict()</code> (loopback only), replaced by <code>bearerAuth</code> under <code>--bearer-token</code> or <code>allowAll()</code> under <code>--allow-anonymous</code>. Session routes also require the caller to be the session&#39;s owner (<code>403</code> otherwise). Errors return JSON <code>{ ok: false, error: &quot;&lt;code&gt;&quot;, message? }</code> with a matching HTTP status.</p><h2 id="host-level-routes-multi-agent-mode" tabindex="-1">Host-level routes (multi-agent mode) <a class="header-anchor" href="#host-level-routes-multi-agent-mode" aria-label="Permalink to &quot;Host-level routes (multi-agent mode)&quot;">​</a></h2><p>These routes live at the host root, above any agent. The two index routes exist only while the playground is enabled (<code>--no-playground</code> removes them) and run no auth. The documentation site is mounted in both layouts and removed by <code>--no-docs</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /</code></td><td>A web index of every mounted agent, linking to playgrounds (playground only)</td></tr><tr><td><code>GET /v1/agents</code></td><td>The JSON index of mounted agents (playground only, no auth)</td></tr><tr><td><code>GET /docs</code>, <code>GET /docs/*</code></td><td>This documentation, served as a static site (both layouts, no auth)</td></tr><tr><td><code>GET /v1/health</code></td><td>Host-level liveness, no auth</td></tr></tbody></table><h2 id="start-a-session" tabindex="-1">Start a session <a class="header-anchor" href="#start-a-session" aria-label="Permalink to &quot;Start a session&quot;">​</a></h2><p><code>POST /v1/session</code> opens a durable conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
+import{_ as t,c as s,o,a3 as a}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use.","frontmatter":{"title":"HTTP API","description":"Public session, discovery, and channel routes callers use."},"headers":[],"relativePath":"reference/http-api.md","filePath":"reference/http-api.md"}'),n={name:"reference/http-api.md"};function d(i,e,r,l,c,h){return o(),s("div",null,[...e[0]||(e[0]=[a(`<h1 id="http-api-reference" tabindex="-1">HTTP API reference <a class="header-anchor" href="#http-api-reference" aria-label="Permalink to &quot;HTTP API reference&quot;">​</a></h1><p>Agent SDK hosts expose the same public HTTP surface. In the default multi-agent layout each agent is namespaced under its slug (<code>/&lt;slug&gt;/v1/session</code>, <code>/&lt;slug&gt;/playground</code>), with host-level routes at the root. With <code>--mode single</code>, one agent serves the same surface unslugged (<code>/v1/*</code>).</p><p>Unless noted otherwise, routes run the agent&#39;s HTTP auth chain: the default is <code>localDevStrict()</code> (loopback only), replaced by <code>bearerAuth</code> under <code>--bearer-token</code> or <code>allowAll()</code> under <code>--allow-anonymous</code>. Session routes also require the caller to be the session&#39;s owner (<code>403</code> otherwise). Errors return JSON <code>{ ok: false, error: &quot;&lt;code&gt;&quot;, message? }</code> with a matching HTTP status.</p><h2 id="host-level-routes-multi-agent-mode" tabindex="-1">Host-level routes (multi-agent mode) <a class="header-anchor" href="#host-level-routes-multi-agent-mode" aria-label="Permalink to &quot;Host-level routes (multi-agent mode)&quot;">​</a></h2><p>These routes live at the host root, above any agent. The two index routes exist only while the playground is enabled (<code>--no-playground</code> removes them) and run no auth. The documentation site is mounted in both layouts and removed by <code>--no-docs</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /</code></td><td>A web index of every mounted agent, linking to playgrounds (playground only)</td></tr><tr><td><code>GET /v1/agents</code></td><td>The JSON index of mounted agents (playground only, no auth)</td></tr><tr><td><code>GET /docs</code>, <code>GET /docs/*</code></td><td>This documentation, served as a static site (both layouts, no auth)</td></tr><tr><td><code>GET /v1/health</code></td><td>Host-level liveness, no auth</td></tr></tbody></table><h2 id="start-a-session" tabindex="-1">Start a session <a class="header-anchor" href="#start-a-session" aria-label="Permalink to &quot;Start a session&quot;">​</a></h2><p><code>POST /v1/session</code> opens a durable conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;message&quot;:&quot;What can you do?&quot;}&#39;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;sessionId&quot;:&quot;ses_…&quot;,&quot;continuationToken&quot;:&quot;http:…&quot;,</span></span>

package/dist/docs/assets/{reference_http-api.md.DTKcYE6L.lean.js → reference_http-api.md.CduHavZ2.lean.js}

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

package/dist/docs/assets/{reference_instructions.md.D7gkckK-.js → reference_instructions.md.CU1My5My.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function o(r,s,h,l,p,d){return i(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="instructions" tabindex="-1">Instructions <a class="header-anchor" href="#instructions" aria-label="Permalink to &quot;Instructions&quot;">​</a></h1><p><code>agent/instructions.md</code> is the always-on system prompt. It&#39;s the one piece of prose the model sees on every turn. It&#39;s required on the root agent; subagents may inline <code>instructions</code> in their <code>agent.ts</code> instead.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Three forms cover every case.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>agent/instructions.md</code></td><td>Plain Markdown for most agents.</td></tr><tr><td><code>agent/instructions.ts</code></td><td>Generated prompts. Default-export <code>defineInstructions({ markdown })</code> or a plain string.</td></tr><tr><td><code>agent/instructions/</code> directory</td><td>A long prompt split across files, composed in filename order.</td></tr></tbody></table><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/instructions.ts</span></span>
+import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function o(r,s,h,l,p,d){return i(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="instructions" tabindex="-1">Instructions <a class="header-anchor" href="#instructions" aria-label="Permalink to &quot;Instructions&quot;">​</a></h1><p><code>agent/instructions.md</code> is the always-on system prompt. It&#39;s the one piece of prose the model sees on every turn. It&#39;s required on the root agent; subagents may inline <code>instructions</code> in their <code>agent.ts</code> instead.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to &quot;Authoring forms&quot;">​</a></h2><p>Three forms cover every case.</p><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>agent/instructions.md</code></td><td>Plain Markdown for most agents.</td></tr><tr><td><code>agent/instructions.ts</code></td><td>Generated prompts. Default-export <code>defineInstructions({ markdown })</code> or a plain string.</td></tr><tr><td><code>agent/instructions/</code> directory</td><td>A long prompt split across files, composed in filename order.</td></tr></tbody></table><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/instructions.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineInstructions } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineInstructions</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>

package/dist/docs/assets/{reference_instructions.md.D7gkckK-.lean.js → reference_instructions.md.CU1My5My.lean.js}

@@ -1 +1 @@
-import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.dypDpWZ3.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function o(r,s,h,l,p,d){return i(),e("div",null,[...s[0]||(s[0]=[a("",17)])])}const u=t(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up.","frontmatter":{"title":"Instructions","description":"The always-on system prompt: authoring forms, how it reaches the model on each runtime, and what makes instructions hold up."},"headers":[],"relativePath":"reference/instructions.md","filePath":"reference/instructions.md"}'),n={name:"reference/instructions.md"};function o(r,s,h,l,p,d){return i(),e("div",null,[...s[0]||(s[0]=[a("",17)])])}const u=t(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{reference_playground.md.D2YExv5K.js → reference_playground.md.Ch2d0Iqi.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),s={name:"reference/playground.md"};function r(l,e,d,i,c,h){return a(),o("div",null,[...e[0]||(e[0]=[n('<h1 id="playground" tabindex="-1">Playground <a class="header-anchor" href="#playground" aria-label="Permalink to &quot;Playground&quot;">​</a></h1><p>Every served agent ships with a web playground at <code>http://127.0.0.1:3000/&lt;slug&gt;/playground</code> (or <code>/playground</code> in single mode). Anything you can do there you can also do with curl.</p><h2 id="what-it-does" tabindex="-1">What it does <a class="header-anchor" href="#what-it-does" aria-label="Permalink to &quot;What it does&quot;">​</a></h2><p>Use the playground to chat, try channel routes, and inspect sessions.</p><ul><li><strong>Chat</strong> with the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state.</li><li><strong>Slash commands</strong>: custom channel routes become composer commands (a <code>drive</code> route becomes <code>/drive &lt;pr-url&gt;</code>), with <code>/help</code> and autocomplete.</li><li><strong>Try</strong> any channel route from the Agent surface. The modal remembers your last body per endpoint and has Copy curl, and a successful Try opens the created session.</li><li><strong>Sessions</strong>: browse the sessions you own (chat, custom-channel, schedule tasks) and replay their event streams. In <code>--dev</code> on loopback, or with <code>--allow-anonymous</code>, the list includes every principal. Search by session ID to filter the list, or press Enter to open an ID directly. &quot;Open trace&quot; renders a saved event stream.</li><li><strong>Approvals</strong>: parked <code>needsApproval</code> tool calls render Approve / Deny buttons.</li><li><strong>Evals</strong>: list and run filesystem evals from the browser (backed by <code>/v1/dev/evals</code>). Schedule hand-dispatch still requires <code>--dev</code>.</li><li><strong>The surface</strong>: inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks.</li><li><strong>Custom tool chips</strong>: drop <code>agent/playground/tools/&lt;toolName&gt;.tsx</code> to change how that tool renders. Chips compile from the agent tree; an <a href="./extensions.html">extension</a> cannot contribute them.</li><li><strong>Raw events pane</strong>: flip it on to inspect the event stream.</li><li><strong>Logs tab</strong>: recent server log lines, polled from <code>GET /v1/logs</code>.</li></ul><p>In multi-agent mode each agent has its own playground at <code>/&lt;slug&gt;/playground</code>, and <code>/</code> is an index of them all.</p><h2 id="share-it-beyond-localhost" tabindex="-1">Share it beyond localhost <a class="header-anchor" href="#share-it-beyond-localhost" aria-label="Permalink to &quot;Share it beyond localhost&quot;">​</a></h2><p>The default <code>localDevStrict()</code> auth admits direct loopback calls only and rejects proxy-forwarding headers, so a tunnel or LAN address won&#39;t work until you pass <code>--bearer-token &lt;secret&gt;</code> (or <code>serve(dir, { authToken })</code>). Open the playground on the remote device and paste the token into the token field in the navbar. <code>--allow-anonymous</code> is the demo-only alternative for trusted networks.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./http-api.html">HTTP API</a>: the HTTP surface the playground uses</li><li><a href="./sessions.html">Sessions and streaming</a>: the streams it renders</li><li><a href="./tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: the approval buttons in context</li></ul>',11)])])}const g=t(s,[["render",r]]);export{u as __pageData,g as default};
+import{_ as t,c as o,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),s={name:"reference/playground.md"};function r(l,e,d,i,c,h){return a(),o("div",null,[...e[0]||(e[0]=[n('<h1 id="playground" tabindex="-1">Playground <a class="header-anchor" href="#playground" aria-label="Permalink to &quot;Playground&quot;">​</a></h1><p>Every served agent ships with a web playground at <code>http://127.0.0.1:3000/&lt;slug&gt;/playground</code> (or <code>/playground</code> in single mode). Anything you can do there you can also do with curl.</p><h2 id="what-it-does" tabindex="-1">What it does <a class="header-anchor" href="#what-it-does" aria-label="Permalink to &quot;What it does&quot;">​</a></h2><p>Use the playground to chat, try channel routes, and inspect sessions.</p><ul><li><strong>Chat</strong> with the agent. Text and reasoning stream live, and tool calls appear inline with their arguments, output, and error state.</li><li><strong>Slash commands</strong>: custom channel routes become composer commands (a <code>drive</code> route becomes <code>/drive &lt;pr-url&gt;</code>), with <code>/help</code> and autocomplete.</li><li><strong>Try</strong> any channel route from the Agent surface. The modal remembers your last body per endpoint and has Copy curl, and a successful Try opens the created session.</li><li><strong>Sessions</strong>: browse the sessions you own (chat, custom-channel, schedule tasks) and replay their event streams. In <code>--dev</code> on loopback, or with <code>--allow-anonymous</code>, the list includes every principal. Search by session ID to filter the list, or press Enter to open an ID directly. &quot;Open trace&quot; renders a saved event stream.</li><li><strong>Approvals</strong>: parked <code>needsApproval</code> tool calls render Approve / Deny buttons.</li><li><strong>Evals</strong>: list and run filesystem evals from the browser (backed by <code>/v1/dev/evals</code>). Schedule hand-dispatch still requires <code>--dev</code>.</li><li><strong>The surface</strong>: inspect the discovered tools, skills, subagents, MCP connections, channels, and hooks.</li><li><strong>Custom tool chips</strong>: drop <code>agent/playground/tools/&lt;toolName&gt;.tsx</code> to change how that tool renders. Chips compile from the agent tree; an <a href="./extensions.html">extension</a> cannot contribute them.</li><li><strong>Raw events pane</strong>: flip it on to inspect the event stream.</li><li><strong>Logs tab</strong>: recent server log lines, polled from <code>GET /v1/logs</code>.</li></ul><p>In multi-agent mode each agent has its own playground at <code>/&lt;slug&gt;/playground</code>, and <code>/</code> is an index of them all.</p><h2 id="share-it-beyond-localhost" tabindex="-1">Share it beyond localhost <a class="header-anchor" href="#share-it-beyond-localhost" aria-label="Permalink to &quot;Share it beyond localhost&quot;">​</a></h2><p>The default <code>localDevStrict()</code> auth admits direct loopback calls only and rejects proxy-forwarding headers, so a tunnel or LAN address won&#39;t work until you pass <code>--bearer-token &lt;secret&gt;</code> (or <code>serve(dir, { authToken })</code>). Open the playground on the remote device and paste the token into the token field in the navbar. <code>--allow-anonymous</code> is the demo-only alternative for trusted networks.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./http-api.html">HTTP API</a>: the HTTP surface the playground uses</li><li><a href="./sessions.html">Sessions and streaming</a>: the streams it renders</li><li><a href="./tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>: the approval buttons in context</li></ul>',11)])])}const g=t(s,[["render",r]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_playground.md.D2YExv5K.lean.js → reference_playground.md.Ch2d0Iqi.lean.js}

@@ -1 +1 @@
-import{_ as t,c as o,o as a,a3 as n}from"./chunks/framework.dypDpWZ3.js";const u=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),s={name:"reference/playground.md"};function r(l,e,d,i,c,h){return a(),o("div",null,[...e[0]||(e[0]=[n("",11)])])}const g=t(s,[["render",r]]);export{u as __pageData,g as default};
+import{_ as t,c as o,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch.","frontmatter":{"title":"Playground","description":"The built-in web UI: chat with streaming, Try buttons and slash commands, session replay, approvals, and dev-mode dispatch."},"headers":[],"relativePath":"reference/playground.md","filePath":"reference/playground.md"}'),s={name:"reference/playground.md"};function r(l,e,d,i,c,h){return a(),o("div",null,[...e[0]||(e[0]=[n("",11)])])}const g=t(s,[["render",r]]);export{u as __pageData,g as default};

package/dist/docs/assets/{reference_project-layout.md.DPxbUJyt.js → reference_project-layout.md.BGhgpy9V.js}

@@ -1,4 +1,4 @@
-import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Agent SDK builds an agent by walking the filesystem under <code>agent/</code>. Each folder has a defined purpose. The path a file lands in determines how the Agent SDK loads it.</p><h2 id="folder-structure" tabindex="-1">Folder structure <a class="header-anchor" href="#folder-structure" aria-label="Permalink to &quot;Folder structure&quot;">​</a></h2><p>For the capabilities below, identity comes from the path.</p><table tabindex="0"><thead><tr><th>Path</th><th>Resolves to</th></tr></thead><tbody><tr><td><code>agent/tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>agent/mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>agent/host-connections/anytool.ts</code></td><td>Host MCP connection <code>anytool</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>agent/skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>agent/subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>agent/extensions/ci.ts</code></td><td>extension mount <code>ci</code>; its contributions become <code>ci__&lt;name&gt;</code></td></tr><tr><td><code>agent/extensions/notion.ts</code></td><td>Cursor plugin mount <code>notion</code> (<code>cursorPlugin</code>); its skills, agents, and MCP servers become <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>agent/channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-overview" tabindex="-1">Project overview <a class="header-anchor" href="#project-overview" aria-label="Permalink to &quot;Project overview&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
+import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="project-layout" tabindex="-1">Project layout <a class="header-anchor" href="#project-layout" aria-label="Permalink to &quot;Project layout&quot;">​</a></h1><p>The Agent SDK builds an agent by walking the filesystem under <code>agent/</code>. Each folder has a defined purpose. The path a file lands in determines how the Agent SDK loads it.</p><h2 id="folder-structure" tabindex="-1">Folder structure <a class="header-anchor" href="#folder-structure" aria-label="Permalink to &quot;Folder structure&quot;">​</a></h2><p>For the capabilities below, identity comes from the path.</p><table tabindex="0"><thead><tr><th>Path</th><th>Resolves to</th></tr></thead><tbody><tr><td><code>agent/tools/approve_pr.ts</code></td><td>tool <code>approve_pr</code></td></tr><tr><td><code>agent/mcp-connections/linear.ts</code></td><td>MCP connection <code>linear</code> (model + host)</td></tr><tr><td><code>agent/host-connections/anytool.ts</code></td><td>Host MCP connection <code>anytool</code> (host + <code>mcp oauth</code> only)</td></tr><tr><td><code>agent/skills/pr-review.md</code></td><td>skill <code>pr-review</code></td></tr><tr><td><code>agent/subagents/reviewer/</code></td><td>subagent <code>reviewer</code></td></tr><tr><td><code>agent/extensions/ci.ts</code></td><td>extension mount <code>ci</code>; its contributions become <code>ci__&lt;name&gt;</code></td></tr><tr><td><code>agent/extensions/notion.ts</code></td><td>Cursor plugin mount <code>notion</code> (<code>cursorPlugin</code>); its skills, agents, and MCP servers become <code>notion__&lt;name&gt;</code></td></tr><tr><td><code>agent/channels/drive.ts</code></td><td>channel <code>drive</code>, routes under <code>/v1/channels/drive</code></td></tr></tbody></table><p>The root agent takes its name from <code>package.json</code> <code>name</code>, falling back to the directory name. When serving multiple agents, the slug is the directory name and must match <code>[A-Za-z0-9][A-Za-z0-9_-]*</code> (and not the reserved <code>v1</code>, <code>playground</code>, or <code>docs</code> segments).</p><h2 id="project-overview" tabindex="-1">Project overview <a class="header-anchor" href="#project-overview" aria-label="Permalink to &quot;Project overview&quot;">​</a></h2><p>Most projects start with this shape.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
 <span class="line"><span>├── package.json</span></span>
 <span class="line"><span>├── agent/</span></span>
 <span class="line"><span>│   ├── agent.ts               # runtime config (model, runtime, cloud/local)</span></span>

package/dist/docs/assets/{reference_project-layout.md.DPxbUJyt.lean.js → reference_project-layout.md.BGhgpy9V.lean.js}

@@ -1 +1 @@
-import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.dypDpWZ3.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",20)])])}const u=t(d,[["render",n]]);export{g as __pageData,u as default};
+import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule.","frontmatter":{"title":"Project layout","description":"The folder structure under agent/ and the path-derived naming rule."},"headers":[],"relativePath":"reference/project-layout.md","filePath":"reference/project-layout.md"}'),d={name:"reference/project-layout.md"};function n(r,e,i,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o("",20)])])}const u=t(d,[["render",n]]);export{g as __pageData,u as default};

package/dist/docs/assets/{reference_prompt.md.BQ5uAv1F.js → reference_prompt.md.Ccp0R53H.js}

@@ -1 +1 @@
-import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.dypDpWZ3.js";const c=JSON.parse('{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors.","frontmatter":{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function p(r,s,l,o,h,d){return t(),i("div",null,[...s[0]||(s[0]=[a('<h1 id="prompt" tabindex="-1"><code>prompt</code> <a class="header-anchor" href="#prompt" aria-label="Permalink to &quot;`prompt`&quot;">​</a></h1><p>Authoring helper for long strings that live next to indented TypeScript: tool descriptions, reminder <code>prompt</code> fields, GitHub channel <code>context</code>, and error messages.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { prompt } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or: import { prompt } from &quot;@cursor/july/prompt&quot;;</span></span></code></pre></div><h2 id="prompt-1" tabindex="-1"><code>prompt\\</code>…`` <a class="header-anchor" href="#prompt-1" aria-label="Permalink to &quot;`prompt\\`…\\``&quot;">​</a></h2><p>Returns a single dedented string. Common leading whitespace is stripped; a leading newline after the opening backtick is dropped so the usual multiline form stays readable in source.</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;">throw</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  It is outside business hours (Mon–Fri 9am–5pm ET).</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Use request_author_approval, or pass approval=human_request.</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Blank lines inside the body are preserved. Relative indentation after the common prefix is kept (handy for nested bullet lists).</p><p>When interpolating multi-line values (for example a list of services), give those lines the same indent as the <code>prompt</code> body so dedent stays consistent.</p><h2 id="prompt-lines" tabindex="-1"><code>prompt.lines\\</code>…`` <a class="header-anchor" href="#prompt-lines" aria-label="Permalink to &quot;`prompt.lines\\`…\\``&quot;">​</a></h2><p>Same dedent rules, but returns <code>string[]</code>, one entry per line. Use this where an API wants separate lines (for example GitHub channel <code>context</code>):</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: prompt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lines</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Merged PR detected: ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} by ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">author</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Call plan_deploy, then follow its nextStep.</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span></code></pre></div>',11)])])}const m=e(n,[["render",p]]);export{c as __pageData,m as default};
+import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors.","frontmatter":{"title":"prompt","description":"Dedented multi-line strings for tool descriptions, reminder prompts, channel context, and errors."},"headers":[],"relativePath":"reference/prompt.md","filePath":"reference/prompt.md"}'),n={name:"reference/prompt.md"};function p(r,s,l,o,h,d){return t(),i("div",null,[...s[0]||(s[0]=[a('<h1 id="prompt" tabindex="-1"><code>prompt</code> <a class="header-anchor" href="#prompt" aria-label="Permalink to &quot;`prompt`&quot;">​</a></h1><p>Authoring helper for long strings that live next to indented TypeScript: tool descriptions, reminder <code>prompt</code> fields, GitHub channel <code>context</code>, and error messages.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { prompt } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>\n<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or: import { prompt } from &quot;@cursor/july/prompt&quot;;</span></span></code></pre></div><h2 id="prompt-1" tabindex="-1"><code>prompt\\</code>…`` <a class="header-anchor" href="#prompt-1" aria-label="Permalink to &quot;`prompt\\`…\\``&quot;">​</a></h2><p>Returns a single dedented string. Common leading whitespace is stripped; a leading newline after the opening backtick is dropped so the usual multiline form stays readable in source.</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;">throw</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  It is outside business hours (Mon–Fri 9am–5pm ET).</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Use request_author_approval, or pass approval=human_request.</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Blank lines inside the body are preserved. Relative indentation after the common prefix is kept (handy for nested bullet lists).</p><p>When interpolating multi-line values (for example a list of services), give those lines the same indent as the <code>prompt</code> body so dedent stays consistent.</p><h2 id="prompt-lines" tabindex="-1"><code>prompt.lines\\</code>…`` <a class="header-anchor" href="#prompt-lines" aria-label="Permalink to &quot;`prompt.lines\\`…\\``&quot;">​</a></h2><p>Same dedent rules, but returns <code>string[]</code>, one entry per line. Use this where an API wants separate lines (for example GitHub channel <code>context</code>):</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: prompt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lines</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Merged PR detected: ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} by ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">author</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">  Call plan_deploy, then follow its nextStep.</span></span>\n<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`</span></span></code></pre></div>',11)])])}const m=e(n,[["render",p]]);export{c as __pageData,m as default};