@cursor/july 0.1.113 → 0.1.114

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

@@ -1,11 +0,0 @@
-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>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;playgroundUrl&quot;:&quot;…?sessionId=ses_…&quot;,&quot;traceUrl&quot;:&quot;…/v1/session/ses_…/events&quot;}</span></span></code></pre></div><p>The response returns as soon as the message is accepted; follow the stream for progress. The continuation token is the follow-up credential, and <code>playgroundUrl</code> deep-links the session in the playground.</p><table tabindex="0"><thead><tr><th>Body field</th><th>Meaning</th></tr></thead><tbody><tr><td><code>message</code></td><td>Required user message</td></tr><tr><td><code>title</code></td><td>Session title</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools</td></tr><tr><td><code>asOf</code></td><td>ISO-8601 instant with a timezone, frozen at create; the prompt states it, <code>ctx.now()</code> returns it, and tool calls with relative, later-than-<code>asOf</code>, or omitted schema-declared time bounds are refused. <code>400</code> when unusable</td></tr><tr><td><code>workspaceFiles</code></td><td>UTF-8 files written into the session workspace</td></tr><tr><td><code>cloud</code></td><td>Per-session cloud options merged over the agent defaults</td></tr></tbody></table><h2 id="send-a-follow-up" tabindex="-1">Send a follow-up <a class="header-anchor" href="#send-a-follow-up" aria-label="Permalink to &quot;Send a follow-up&quot;">​</a></h2><p><code>POST /v1/session/:sessionId</code> continues an existing conversation.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/session/ses_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;continuationToken&quot;:&quot;http:…&quot;,&quot;message&quot;:&quot;Make it shorter.&quot;}&#39;</span></span></code></pre></div><p>Works for any chat session, including ones created by custom channels. Each accepted follow-up rotates the token, and the response carries the new one. Sending to a busy session interrupts the in-flight turn, waits for it to settle, then sends.</p><p>Expect <code>409</code> on a stale token or a task session. Task sessions do not accept follow-ups. Expect <code>403</code> when the caller is not the session owner.</p><h2 id="stream-a-session" tabindex="-1">Stream a session <a class="header-anchor" href="#stream-a-session" aria-label="Permalink to &quot;Stream a session&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/stream</code> is the live NDJSON feed.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>One NDJSON event per line, from <code>startIndex</code>, then following live. The default is <code>0</code>: omitting the parameter replays the entire recorded stream before following. Pass the last index you&#39;ve seen plus one to resume without duplicates. The stream is durable and reconnectable. For the vocabulary, see <a href="./sessions.html#which-events-can-i-stream">Sessions</a>.</p><p><code>GET /v1/session/:sessionId/events</code> returns a one-shot NDJSON dump. Pass <code>?format=json</code> for <code>{ sessionId, events, playgroundUrl }</code>.</p><h2 id="stop-and-list" tabindex="-1">Stop and list <a class="header-anchor" href="#stop-and-list" aria-label="Permalink to &quot;Stop and list&quot;">​</a></h2><p><code>POST /v1/session/:sessionId/stop</code> interrupts the in-flight turn without sending a new message. <code>GET /v1/sessions</code> lists sessions owned by the calling principal. Under <code>serve --dev</code> on loopback it includes all sessions, which is how webhook and schedule sessions show up in the playground.</p><h2 id="session-cost" tabindex="-1">Session cost <a class="header-anchor" href="#session-cost" aria-label="Permalink to &quot;Session cost&quot;">​</a></h2><p><code>GET /v1/session/:sessionId/cost</code> returns the session&#39;s cost report: per-turn token usage and the engine&#39;s estimated cost, folded from <code>turn.completed</code> events. It runs the same owner check as the other session routes and returns <code>404</code> for an unknown session. The <a href="./cli.html#cost"><code>agent-sdk cost</code></a> command reports the same data.</p><h2 id="approvals" tabindex="-1">Approvals <a class="header-anchor" href="#approvals" aria-label="Permalink to &quot;Approvals&quot;">​</a></h2><p>Two routes list and resolve parked tool calls.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/session/:sessionId/approvals</code></td><td>Pending human-in-the-loop tool approvals</td></tr><tr><td><code>POST /v1/session/:sessionId/approvals/:callId</code></td><td>Resolve one: <code>{&quot;decision&quot;:&quot;approve&quot;}</code> or <code>{&quot;decision&quot;:&quot;deny&quot;}</code></td></tr></tbody></table><p>For the lifecycle, see <a href="./tools.html#gate-a-tool-on-human-approval">Gate a tool on human approval</a>.</p><h2 id="call-a-tool-directly" tabindex="-1">Call a tool directly <a class="header-anchor" href="#call-a-tool-directly" aria-label="Permalink to &quot;Call a tool directly&quot;">​</a></h2><p><code>POST /v1/tools/:toolName</code> runs a server tool with no model turn.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;content-type: application/json&#39;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;input&quot;:{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}}&#39;</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;ok&quot;:true,&quot;toolName&quot;:&quot;inspect_pr&quot;,&quot;callId&quot;:&quot;tool_inspect_pr_…&quot;,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">#  &quot;isError&quot;:false,&quot;result&quot;:{…},&quot;durationMs&quot;:12}</span></span></code></pre></div><p>It runs an authored server tool in-process: schema-validated, no model turn. An optional <code>&quot;sessionId&quot;</code> in the body runs it inside an existing session and records it on that session&#39;s stream (<code>409 session_busy</code> for a write-effect call while a turn runs; reads run alongside the turn). Agent-execution tools are rejected with <code>400</code>, and unknown tools with <code>404</code> and the list of available names. For the semantics, see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>.</p><p>An optional <code>&quot;continuationToken&quot;</code> (<code>&lt;channelId&gt;:&lt;key&gt;</code>, as <code>/v1/sessions</code> lists it; mutually exclusive with <code>sessionId</code>) addresses the session by continuation token instead; malformed tokens are rejected with <code>400 invalid_continuation_token</code>. For the semantics, see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>.</p><h2 id="discovery" tabindex="-1">Discovery <a class="header-anchor" href="#discovery" aria-label="Permalink to &quot;Discovery&quot;">​</a></h2><p>These read-only routes describe the running agent.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/info</code></td><td>The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, diagnostics</td></tr><tr><td><code>GET /v1/tools</code></td><td>The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light <code>{ name, title?, source? }</code> entries. <code>session</code> / <code>continuationToken</code> query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in <code>connectionErrors</code></td></tr><tr><td><code>GET /v1/tools/:name</code></td><td>One catalog tool&#39;s full description: description, execution, <code>needsApproval</code>, <code>effect</code>, input and output schemas, source connection. Same session binding as the listing; unknown names get <code>404</code> with the available names</td></tr><tr><td><code>GET /v1/health</code></td><td>Per-agent liveness, no auth</td></tr><tr><td><code>GET /v1/logs?after=N</code></td><td>Recent server log lines, with a polling cursor</td></tr></tbody></table><h2 id="artifacts" tabindex="-1">Artifacts <a class="header-anchor" href="#artifacts" aria-label="Permalink to &quot;Artifacts&quot;">​</a></h2><p>Two routes read durable artifacts tagged by <code>ctx.artifacts</code> or <code>tag_artifact</code>. See <a href="./artifacts.html">Artifacts</a>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/artifacts</code></td><td>List artifacts as <code>{ artifacts }</code>, newest-updated first. Filter with <code>?kind=</code>, <code>?sessionId=</code>, and <code>?limit=</code> (a positive integer)</td></tr><tr><td><code>GET /v1/artifacts/:id/content</code></td><td>Download one artifact&#39;s file or blob payload. Served as an attachment, never rendered inline; <code>404</code> when the artifact is unknown or carries no content</td></tr></tbody></table><p>Session ownership applies the same way as <code>GET /v1/sessions</code>: under <code>serve --dev</code> on loopback (or <code>--allow-anonymous</code>) the list spans all principals, while bearer or custom channel auth keeps strict per-principal isolation.</p><h2 id="custom-channel-routes" tabindex="-1">Custom channel routes <a class="header-anchor" href="#custom-channel-routes" aria-label="Permalink to &quot;Custom channel routes&quot;">​</a></h2><p>Authored routes mount under <code>/v1/channels/&lt;id&gt;</code> with the methods, paths, and Zod schemas the channel declared (a <code>POST /&lt;slug&gt;/v1/channels/drive</code> route, say). Bodies are validated before handlers run (<code>400</code> on schema violations), and each channel&#39;s auth chain applies. The GitHub channel verifies <code>X-Hub-Signature-256</code> when a secret is configured. See <a href="./channels.html">Channels</a>.</p><h2 id="mcp-endpoint" tabindex="-1">MCP endpoint <a class="header-anchor" href="#mcp-endpoint" aria-label="Permalink to &quot;MCP endpoint&quot;">​</a></h2><p><code>/v1/mcp</code> serves the Model Context Protocol over streamable HTTP (stateless; POST carries the protocol, and GET/DELETE return spec-compliant 405s). The tools are <code>ask</code> (delegate a message, bounded waits), <code>check</code> (poll a running session), and <code>call_tool</code> (deterministic server-tool passthrough, present when the agent has server tools). The route runs the same auth chain as the session API. Peer wiring: <a href="./connections.html#peer-mcp-connection">MCP connections</a>.</p><p><code>/v1/mcp/tools</code> is a second stateless MCP endpoint exposing only the agent&#39;s deterministic server tools. Hosted cloud turns call back into it through the URL configured by <code>serve --cloud-tools-url</code>. Unlike <code>/v1/mcp</code>, it runs the CLI-level auth chain (loopback, bearer, or anonymous), not any authored channel auth.</p><h2 id="playground-eval-routes" tabindex="-1">Playground eval routes <a class="header-anchor" href="#playground-eval-routes" aria-label="Permalink to &quot;Playground eval routes&quot;">​</a></h2><p>The playground Evals tab and <code>agent-sdk eval --prod</code> / <code>--url</code> use these:</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>GET /v1/dev/evals</code></td><td>List discovered eval datapoints and project config</td></tr><tr><td><code>GET /v1/dev/evals/runs</code></td><td>List recent run snapshots, newest first</td></tr><tr><td><code>POST /v1/dev/evals/runs</code></td><td>Start an eval run (<code>{filterIds?, tags?}</code>); <code>202</code> with a snapshot (<code>runId</code> is the Eval ID), <code>404</code> when nothing matches, <code>409</code> when one is running</td></tr><tr><td><code>GET /v1/dev/evals/runs/:runId</code></td><td>Poll a run&#39;s progress</td></tr><tr><td><code>POST /v1/dev/evals/runs/:runId/cancel</code></td><td>Cancel a running batch; <code>200</code> with snapshot, <code>404</code> unknown, <code>409</code> when not running</td></tr></tbody></table><p>Eval runs are asynchronous. Poll the run route for case progress and the final <code>completed</code> or <code>failed</code> status. Batch errors appear on the snapshot returned by the poll. Entries within <code>filterIds</code> and <code>tags</code> use OR semantics. When both fields are present, a case must match one entry from each field. Listed runs persist across restarts when durable storage is configured. Otherwise they are process-memory only.</p><h2 id="dev-mode-routes" tabindex="-1">Dev-mode routes <a class="header-anchor" href="#dev-mode-routes" aria-label="Permalink to &quot;Dev-mode routes&quot;">​</a></h2><p>These routes exist only under <code>serve --dev</code>.</p><table tabindex="0"><thead><tr><th>Route</th><th>What it does</th></tr></thead><tbody><tr><td><code>POST /v1/dev/schedules/:scheduleId</code></td><td>Dispatch a schedule by hand, exactly once. Returns <code>{scheduleId, sessionIds}</code></td></tr><tr><td><code>GET /v1/dev/reminders</code></td><td>List reminders</td></tr><tr><td><code>POST /v1/dev/reminders/:reminderId</code></td><td>Fire a reminder by hand</td></tr></tbody></table><p>Schedules and reminders never fire automatically in dev mode. These routes are the only way they run, which keeps iteration deterministic.</p><h2 id="playground-assets" tabindex="-1">Playground assets <a class="header-anchor" href="#playground-assets" aria-label="Permalink to &quot;Playground assets&quot;">​</a></h2><p><code>GET /playground</code> and <code>GET /playground/assets/:file</code> serve the playground (omitted with <code>--no-playground</code>). It calls the JSON API above and has no privileged surface.</p><h2 id="status-codes" tabindex="-1">Status codes <a class="header-anchor" href="#status-codes" aria-label="Permalink to &quot;Status codes&quot;">​</a></h2><p>Error responses use a small, consistent set of status codes.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning here</th></tr></thead><tbody><tr><td><code>400</code></td><td>Schema-invalid body or query, agent-execution tool called on the host, malformed request</td></tr><tr><td><code>401</code></td><td>No auth policy admitted the request</td></tr><tr><td><code>403</code></td><td>Authenticated, but not the session owner</td></tr><tr><td><code>404</code></td><td>Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request</td></tr><tr><td><code>405</code></td><td>Wrong method (GET on the MCP endpoint, say)</td></tr><tr><td><code>409</code></td><td>Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress</td></tr><tr><td><code>202</code></td><td>Accepted for background work (GitHub <code>{ task }</code> hooks, eval runs)</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./sessions.html">Sessions and streaming</a>: the handles and events these routes traffic in</li><li><a href="./channels.html">Channels</a>: authoring your own routes</li><li><a href="./../deployment.html">Deployment</a>: auth on real hosts</li></ul>`,62)])])}const k=t(n,[["render",d]]);export{p as __pageData,k as default};

package/dist/docs/assets/reference_instructions.md.CU1My5My.js

@@ -1,14 +0,0 @@
-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>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`You are the on-call assistant for \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">process</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">TEAM_NAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="how-instructions-reach-the-model" tabindex="-1">How instructions reach the model <a class="header-anchor" href="#how-instructions-reach-the-model" aria-label="Permalink to &quot;How instructions reach the model&quot;">​</a></h2><p>On the local runtime, instructions land in the session workspace as <code>AGENTS.md</code>, and the harness loads them natively. On the cloud runtime, they&#39;re prepended to the first prompt, because the cloud VM doesn&#39;t share the local session workspace.</p><p>The local workspace is a real Cursor project directory, so the harness may also load ambient <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. <a href="./agent-config.html#local-cwd">Agent config → Local cwd</a> covers controlling that.</p><h2 id="what-to-put-in-instructions" tabindex="-1">What to put in instructions <a class="header-anchor" href="#what-to-put-in-instructions" aria-label="Permalink to &quot;What to put in instructions&quot;">​</a></h2><p>Keep them a few lines: identity, when to use which tool, output shape. The <a href="./../quickstart.html">quickstart PR approver</a> is the pattern:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR approver</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">You review GitHub pull requests. Be specific and brief.</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Call </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`inspect_pr\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> first. Never judge a change you haven&#39;t fetched.</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Match your review to the complexity it reports.</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Never approve a draft.</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">End with one sentence: the verdict and why.</span></span></code></pre></div><ul><li>Name the tools and the decision rule (&quot;use X before answering about Y&quot;), not general encouragement.</li><li>State the output contract: length, format, fences. That contract is what your <a href="./../evals.html">evals</a> gate.</li><li>Move procedures to <a href="./skills.html">skills</a>. A multi-step workflow the model only sometimes needs belongs in <code>agent/skills/</code>, where it loads on demand and keeps the always-on prompt small.</li></ul><p>Instructions are the third lever in the <a href="./../hillclimbing.html">hillclimbing loop</a>, after host preparation and evidence shape. If a fixture keeps failing, look there before rewriting prose.</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="./skills.html">Skills</a>: procedures the model loads only when relevant</li><li><a href="./agent-config.html">Agent config</a>: the file next to this one</li><li><a href="./../hillclimbing.html">Hillclimbing</a>: iterating on instructions with evidence</li></ul>`,17)])])}const u=t(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_instructions.md.CU1My5My.lean.js

@@ -1 +0,0 @@
-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.Ch2d0Iqi.js

@@ -1 +0,0 @@
-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.Ch2d0Iqi.lean.js

@@ -1 +0,0 @@
-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.BGhgpy9V.js

@@ -1,19 +0,0 @@
-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>
-<span class="line"><span>│   ├── instructions.md        # always-on system prompt (required)</span></span>
-<span class="line"><span>│   ├── tools/</span></span>
-<span class="line"><span>│   │   └── approve_pr.ts      # one typed tool per file</span></span>
-<span class="line"><span>│   ├── skills/</span></span>
-<span class="line"><span>│   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)</span></span>
-<span class="line"><span>│   ├── mcp-connections/</span></span>
-<span class="line"><span>│   │   └── linear.ts          # tools from external MCP servers</span></span>
-<span class="line"><span>│   ├── host-connections/</span></span>
-<span class="line"><span>│   │   └── anytool.ts         # privileged MCP, host tools only</span></span>
-<span class="line"><span>│   └── channels/</span></span>
-<span class="line"><span>│       └── github.ts          # messages and external events</span></span>
-<span class="line"><span>└── evals/</span></span>
-<span class="line"><span>    └── readiness.eval.ts      # regression cases</span></span></code></pre></div><p>Evals live in <code>evals/</code> at the project root, a sibling of <code>agent/</code>, never inside it. <code>agent/evals/</code> is silently ignored. See <a href="./../evals.html">Evals</a>.</p><h2 id="folder-reference" tabindex="-1">Folder reference <a class="header-anchor" href="#folder-reference" aria-label="Permalink to &quot;Folder reference&quot;">​</a></h2><p>Each path maps to a capability and a reference page.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th><th>Reference</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td><code>defineAgent({ model?, runtime?, cloud?, local? })</code>; the model defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code></td><td><a href="./agent-config.html">Agent config</a></td></tr><tr><td><code>agent/instructions.md</code></td><td>Always-on system prompt, required on the root agent (<code>.ts</code> and directory forms exist)</td><td><a href="./instructions.html">Instructions</a></td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>One typed tool; filename = tool name. <code>execution: &quot;server&quot;</code> (in-process, default) or <code>&quot;agent&quot;</code> (a script that runs where the agent runs)</td><td><a href="./tools.html">Tools</a></td></tr><tr><td><code>agent/skills/*</code></td><td>SKILL.md-convention procedures, loaded on demand</td><td><a href="./skills.html">Skills</a></td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>MCP servers, available to the model, to server tools (<code>ctx.host.mcp</code>), and to channel/schedule handlers (<code>args.host.mcp</code>)</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/host-connections/&lt;name&gt;.ts</code></td><td>Privileged MCP servers for <code>ctx.host.mcp</code> and <code>mcp oauth</code>. The model never sees them.</td><td><a href="./connections.html">MCP connections</a></td></tr><tr><td><code>agent/subagents/&lt;id&gt;/</code></td><td>Child agent directory; <code>description</code> required</td><td><a href="./subagents.html">Subagents</a></td></tr><tr><td><code>agent/extensions/&lt;ns&gt;.ts</code> or <code>agent/extensions/&lt;ns&gt;/</code></td><td>A mounted extension or Cursor plugin; its contributions become <code>&lt;ns&gt;__&lt;name&gt;</code></td><td><a href="./extensions.html">Extensions</a></td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP surfaces beyond the built-in session API; <code>slack.ts</code> and <code>github.ts</code> use the platform packs</td><td><a href="./channels.html">Channels</a></td></tr><tr><td><code>agent/hooks/*.ts</code></td><td>Observe-only event subscribers, never fatal</td><td><a href="./hooks.html">Hooks</a></td></tr><tr><td><code>agent/otel.ts</code></td><td>Factory-only OTLP authoring (<code>defineOtel</code>). Public path is env / <code>serve({ otel })</code>.</td><td><a href="./../guides/opentelemetry.html">OpenTelemetry</a></td></tr><tr><td><code>agent/storage.ts</code></td><td><code>defineStorage</code> backend for the durable <code>host.kv</code> / <code>host.files</code> APIs</td><td>None</td></tr><tr><td><code>agent/artifacts.ts</code></td><td><code>defineArtifacts</code> kinds, the <code>tag_artifact</code> opt-in, and retention</td><td><a href="./artifacts.html">Artifacts</a></td></tr><tr><td><code>agent/result.ts</code></td><td><code>defineResult</code> host <code>commit</code> on the final assistant text (<code>throw</code> or <code>ctx.reject</code>)</td><td>None</td></tr><tr><td><code>agent/schedules/*</code></td><td>Cron-driven runs (UTC, 5-field; never auto-fire under <code>--dev</code>)</td><td><a href="./schedules.html">Schedules</a></td></tr><tr><td><code>agent/sandbox/workspace/**</code></td><td>Seed files copied into each local session workspace</td><td><a href="./sessions.html#what-goes-into-a-local-session-workspace">Sessions</a></td></tr><tr><td><code>agent/playground/</code></td><td>Custom playground tool chips</td><td><a href="./playground.html">Playground</a></td></tr><tr><td><code>agent/lib/</code></td><td>Import-only shared code, never discovered</td><td>None</td></tr><tr><td><code>evals/evals.config.ts</code></td><td>Shared eval settings (e.g. <code>maxConcurrency</code>); required when evals exist</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Filesystem evals; case id = path under <code>evals/</code></td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p><code>agent/lib/</code> is the only place for shared code. Everything else under <code>agent/</code> is discovery surface. A stray <code>.ts</code> file in one of these folders is treated as a definition.</p><h2 id="why-didn-t-the-agent-sdk-discover-my-file" tabindex="-1">Why didn&#39;t the Agent SDK discover my file? <a class="header-anchor" href="#why-didn-t-the-agent-sdk-discover-my-file" aria-label="Permalink to &quot;Why didn&#39;t the Agent SDK discover my file?&quot;">​</a></h2><p>Run <code>agent-sdk validate --dir .</code> and <code>agent-sdk info --dir .</code>. <code>validate</code> prints diagnostics, and <code>serve</code> refuses to start on error-severity ones. Warnings, such as cloud runtime combined with local-only capabilities, print but don&#39;t block. <code>info</code> lists the discovered surface, so a missing tool or channel shows up immediately. From there, check the folder reference: the file is usually in the wrong directory or has the wrong 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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    # diagnostics; non-zero exit on errors</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:#6A737D;--shiki-dark:#6A737D;">        # human-readable surface</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 style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # machine-readable project info (same shape as GET /v1/info)</span></span></code></pre></div><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./agent-config.html">Agent config</a>: the runtime config at the root</li><li><a href="./tools.html">Tools</a>: add typed actions under <code>agent/tools/</code></li></ul>`,20)])])}const u=t(d,[["render",n]]);export{g as __pageData,u as default};

package/dist/docs/assets/reference_prompt.md.Ccp0R53H.js

@@ -1 +0,0 @@
-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};

package/dist/docs/assets/reference_prompt.md.Ccp0R53H.lean.js

@@ -1 +0,0 @@
-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("",11)])])}const m=e(n,[["render",p]]);export{c as __pageData,m as default};

package/dist/docs/assets/reference_schedules.md.B2Nm6FaD.js

@@ -1,82 +0,0 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>Two ways an agent acts without an inbound message. A schedule is deploy-time cron: &quot;every weekday at 09:00, summarize open incidents.&quot; A reminder is a runtime wake bound to one conversation: &quot;re-check this PR&#39;s CI in two hours.&quot; Schedules live in the filesystem; reminders are created by running code.</p><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><p>Cron expressions are standard 5-field, evaluated in UTC with minute granularity.</p><h3 id="schedules-in-markdown" tabindex="-1">Schedules in Markdown <a class="header-anchor" href="#schedules-in-markdown" aria-label="Permalink to &quot;Schedules in Markdown&quot;">​</a></h3><p>A plain markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cron: &quot;0 9 * * 1-5&quot;</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Pull open incidents and post a summary to the metrics endpoint.</span></span></code></pre></div><p>Each firing starts a task-mode session: the body is the prompt, the session runs to <code>session.completed</code> or <code>session.failed</code>, and it isn&#39;t followable.</p><h3 id="schedules-as-handlers" tabindex="-1">Schedules as handlers <a class="header-anchor" href="#schedules-as-handlers" aria-label="Permalink to &quot;Schedules as handlers&quot;">​</a></h3><p><code>defineSchedule</code> with a <code>run</code> handler gives you full control, most usefully to hand the work into a channel so its delivery events fire:</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;"> { defineSchedule } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/schedules&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;"> webhook </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../channels/webhook.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;"> defineSchedule</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  cron: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;*/30 * * * *&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;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">receive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">appAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">host</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">    // optional: await host.mcp.callTool(&quot;units&quot;, &quot;celsius_to_fahrenheit&quot;, { value: 0 });</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      receive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(webhook, {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        message:</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">          &quot;Check for new critical alerts. Report only when there are any.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        auth: appAuth,</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><code>defineSchedule</code> requires exactly one of <code>markdown</code> or <code>run</code>. The <code>run</code> handler receives <code>receive</code> (hand off into a channel), <code>callTool</code> (deterministic server-tool calls), <code>waitUntil</code>, <code>appAuth</code> (a schedule-scoped principal for work the agent does on its own behalf), and <code>host</code> (shared services: <code>host.mcp</code>, <code>host.github</code>, <code>host.slack</code>, <code>host.reminders</code>).</p><h3 id="dispatch-and-dev-mode" tabindex="-1">Dispatch and dev mode <a class="header-anchor" href="#dispatch-and-dev-mode" aria-label="Permalink to &quot;Dispatch and dev mode&quot;">​</a></h3><p>In production (<code>agent-sdk serve</code>), schedules fire on their cron cadence. Disable them with <code>--no-schedules</code>. There&#39;s no cross-host coordination, so run them in exactly one process per project.</p><p>In dev (<code>serve --dev</code>), schedules never fire automatically. Dispatch one by hand, exactly once, through the same path production uses:</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/dev/schedules/heartbeat</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {&quot;scheduleId&quot;:&quot;heartbeat&quot;,&quot;sessionIds&quot;:[&quot;ses_…&quot;]}</span></span></code></pre></div><p>The playground can dispatch schedules in dev mode too, and <code>handle.dispatchSchedule(&quot;heartbeat&quot;)</code> does it programmatically.</p><h2 id="reminders" tabindex="-1">Reminders <a class="header-anchor" href="#reminders" aria-label="Permalink to &quot;Reminders&quot;">​</a></h2><p>A reminder is created at runtime and bound to a channel continuation. When it fires, it wakes that conversation. Recurring reminders behave like <code>setInterval</code>, one-shots like <code>setTimeout</code>, and both are durable on disk.</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;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createReminder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  purpose: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ci_recheck&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  channelId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;drive&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pr:owner/repo#1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  delay: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;2h&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// or a cron / explicit schedule</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  prompt: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Re-check CI. Only act if still failing.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  until: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Cancel once CI is green or the PR is merged.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Use <code>run</code> when host code should decide what happens on each tick:</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;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createReminder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  purpose: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ci_recheck&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  channelId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;drive&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pr:owner/repo#1&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  every: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;30m&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;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">fireCount</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">followup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (fireCount </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">      return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { action: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stop&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> followup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Re-check CI and report only if the status changed.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    });</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { action: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;delivered&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This reminder wakes the conversation three times, then stops itself.</p><p>The same API is <code>host.reminders</code> on channel handlers, tools, and schedule runs. An agent can even be given a tool that creates its own reminders.</p><p>For example, create <code>agent/tools/remind_me.ts</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;"> { 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;"> { 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;"> 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;Schedule a one-time reminder in this conversation.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  inputSchema: 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;">    delay: z</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      .</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;">      .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;When to wake the conversation, such as 20m or 2h&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    prompt: z</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      .</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;">      .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">min</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;">      .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">describe</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;What the agent should do when it wakes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }),</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">  async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">delay</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prompt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> reminders</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.host.reminders;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (reminders </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<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:#032F62;--shiki-dark:#9ECBFF;">&quot;Reminders are disabled on this host.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> continuationToken</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.session.continuationKey;</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (continuationToken </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
-<span class="line"><span style="--shiki-light:#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:#032F62;--shiki-dark:#9ECBFF;">&quot;This session cannot receive reminder follow-ups.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> reminder</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;"> reminders.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">create</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      purpose: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;user_follow_up&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      channelId: ctx.session.channelId,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      continuationToken,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      delay,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      prompt,</span></span>
-<span class="line"><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;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      reminderId: reminder.id,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      nextFireAt: reminder.nextFireAt,</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>The tool binds the reminder to the current channel conversation. When the delay expires, the prompt returns to the same session as a follow-up.</p><p>Reminders fire in one of two styles. The <strong>prompt form</strong> (above) sends <code>prompt</code> into the session, with <code>until</code> stating the standing cancellation condition for the model to honor. The <strong>run form</strong> passes a <code>run</code> handler instead: it returns <code>stop</code>, <code>skip</code>, or <code>delivered</code> per tick. That&#39;s silent host-side policy with no model turn. Run handlers are in-memory, so after a restart those reminders are disarmed (<code>handler_lost_on_restart</code>); re-arm them from the code path that created them, or prefer the prompt form.</p><p><code>--dev</code> does not auto-fire reminders. Dispatch one by hand:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#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/dev/reminders</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">             # list</span></span>
-<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/dev/reminders/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  # fire one</span></span></code></pre></div><p><code>handle.dispatchReminder(id)</code> is the programmatic equivalent.</p><p>Two habits worth copying: cancel reminders when their subject dies (say, cancel PR-scoped reminders on <code>pull_request.closed</code>), and keep wake prompts generic. A plain &quot;re-check the PR&quot; works better than replaying stale payload details, because the agent re-reads the live state when it wakes.</p><h2 id="schedule-or-reminder" tabindex="-1">Schedule or reminder? <a class="header-anchor" href="#schedule-or-reminder" aria-label="Permalink to &quot;Schedule or reminder?&quot;">​</a></h2><p>The split comes down to scope and timing.</p><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>at deploy time, <code>agent/schedules/*</code></td><td>at runtime, <code>createReminder</code> / <code>host.reminders</code></td></tr><tr><td>Scope</td><td>global to the agent</td><td>one channel continuation (one conversation)</td></tr><tr><td>Session</td><td>starts a new task session (or hands off through <code>receive</code>)</td><td>wakes an existing conversation</td></tr><tr><td>Cadence</td><td>cron (UTC)</td><td>delay, cron, or explicit schedule</td></tr><tr><td>Dev mode</td><td>manual dispatch only</td><td>manual dispatch only (timers off)</td></tr></tbody></table><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./channels.html">Channels</a>: <code>receive</code> and the delivery events</li><li><a href="./../guides/github.html">GitHub guide</a>: reminders in a real webhook loop</li><li><a href="./http-api.html#dev-mode-routes">HTTP API</a>: the dev dispatch routes</li></ul>`,38)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};

package/dist/docs/assets/reference_schedules.md.B2Nm6FaD.lean.js

@@ -1 +0,0 @@
-import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,p,k,d,r){return n(),a("div",null,[...s[0]||(s[0]=[e("",38)])])}const c=i(t,[["render",h]]);export{E as __pageData,c as default};

package/dist/docs/assets/reference_sessions.md.1_6Vyv7x.js

@@ -1 +0,0 @@
-import{_ as t,c as s,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(i,e,r,c,l,h){return a(),s("div",null,[...e[0]||(e[0]=[o('<h1 id="sessions-events-and-streaming" tabindex="-1">Sessions, events, and streaming <a class="header-anchor" href="#sessions-events-and-streaming" aria-label="Permalink to &quot;Sessions, events, and streaming&quot;">​</a></h1><p>A session keeps one conversation, its workspace, and an append-only record of every message and tool call.</p><h2 id="what-does-a-session-contain" tabindex="-1">What does a session contain? <a class="header-anchor" href="#what-does-a-session-contain" aria-label="Permalink to &quot;What does a session contain?&quot;">​</a></h2><p>Each session combines:</p><ul><li>A channel and authenticated caller</li><li>A conversation the caller can continue</li><li>A workspace for local turns</li><li>An NDJSON event stream</li><li>Runtime state needed to resume after a server restart</li></ul><p>Sessions belong to the principal that created them. Follow-up, stream, and list routes return <code>403</code> when another caller tries to access one.</p><h2 id="which-session-identifier-should-i-use" tabindex="-1">Which session identifier should I use? <a class="header-anchor" href="#which-session-identifier-should-i-use" aria-label="Permalink to &quot;Which session identifier should I use?&quot;">​</a></h2><p>Sessions have two identifiers because conversation routing and inspection are different jobs.</p><table tabindex="0"><thead><tr><th>Identifier</th><th>Use it for</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Continue a conversation through its channel</td></tr><tr><td><code>sessionId</code></td><td>Stream events, inspect state, resolve approvals, or run a session-bound tool call</td></tr></tbody></table><p>Channels decide what a continuation token looks like. Slack uses its thread identity. A PR channel can use a key such as <code>pr:owner/repo#1</code>. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up. Reusing a stale HTTP token returns <code>409</code>.</p><p>Use the continuation token to keep talking. Use the session ID to observe or manage the stored session.</p><h2 id="which-session-modes-are-available" tabindex="-1">Which session modes are available? <a class="header-anchor" href="#which-session-modes-are-available" aria-label="Permalink to &quot;Which session modes are available?&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Mode</th><th>Created by</th><th>What happens after a turn</th></tr></thead><tbody><tr><td><code>chat</code></td><td>HTTP sessions, channel <code>send</code>, Slack, or MCP <code>ask</code></td><td>Waits in <code>session.waiting</code> and accepts follow-ups</td></tr><tr><td><code>task</code></td><td>Markdown schedules and fire-and-forget dispatch</td><td>Ends in <code>session.completed</code> or <code>session.failed</code></td></tr></tbody></table><p>Task sessions don&#39;t accept follow-ups. Trying one returns <code>409</code>.</p><h2 id="what-happens-when-i-send-a-follow-up" tabindex="-1">What happens when I send a follow-up? <a class="header-anchor" href="#what-happens-when-i-send-a-follow-up" aria-label="Permalink to &quot;What happens when I send a follow-up?&quot;">​</a></h2><p>A follow-up to an idle chat session starts another turn. Admission when the session is already busy depends on the channel:</p><table tabindex="0"><thead><tr><th>Path</th><th>Busy-session policy</th></tr></thead><tbody><tr><td>HTTP playground / <code>POST /v1/session/:id</code> / MCP <code>ask</code></td><td><strong>Preempt</strong> (default): interrupt the in-flight turn, wait for it to settle, then run the new message</td></tr><tr><td>Slack mentions / DMs / alert-watch</td><td><strong>Coalesce</strong>: leave the active turn running, enqueue the follow-up, and drain queued asks into one follow-up turn when the active turn finishes (no mid-turn tool/hook inject)</td></tr></tbody></table><p>Pass <code>admission: &quot;coalesce&quot;</code> on <code>send()</code> to opt into the Slack policy from other callers. Omit it (or pass <code>&quot;preempt&quot;</code>) to keep interrupt semantics.</p><p><code>POST /v1/session/:id/stop</code> interrupts a turn without sending a new message. Interrupted turns record <code>turn.failed</code> with <code>&quot;turn interrupted&quot;</code>. This means the turn was preempted. A whole-message Slack <code>stop</code> / <code>@agent stop</code> does the same for that thread and clears pending coalesced nudges.</p><p>Session-bound deterministic tool calls share the lock only for writes: a write-effect call returns <code>409 session_busy</code> while a model turn is running, a read-effect call runs alongside the turn (see <a href="./tools.html#call-a-tool-without-a-model-turn">Tools</a>).</p><h2 id="which-events-can-i-stream" tabindex="-1">Which events can I stream? <a class="header-anchor" href="#which-events-can-i-stream" aria-label="Permalink to &quot;Which events can I stream?&quot;">​</a></h2><p>Each NDJSON line uses this envelope: <code>{ type, index, sessionId, turnId?, at, data }</code>. The <code>index</code> increases within one session. The <code>at</code> field is an ISO-8601 timestamp.</p><table tabindex="0"><thead><tr><th>Phase</th><th>Events</th><th>What they tell you</th></tr></thead><tbody><tr><td>Session</td><td><code>session.started</code>, <code>session.waiting</code>, <code>session.completed</code>, <code>session.failed</code></td><td>Session creation, readiness, and task completion</td></tr><tr><td>Agent</td><td><code>agent.bound</code></td><td>Cloud conversation URL</td></tr><tr><td>Input</td><td><code>message.received</code></td><td>A user message was accepted</td></tr><tr><td>Turn</td><td><code>turn.queued</code>, <code>turn.started</code>, <code>turn.completed</code>, <code>turn.failed</code></td><td>Queue position under a <a href="./agent-config.html#concurrency"><code>maxRunningTurns</code> cap</a>, then turn status, final result, and token usage</td></tr><tr><td>Steps</td><td><code>step.started</code>, <code>step.completed</code></td><td>Model step boundaries and duration</td></tr><tr><td>Reasoning</td><td><code>reasoning.appended</code>, <code>reasoning.completed</code></td><td>Streamed reasoning blocks</td></tr><tr><td>Reply</td><td><code>message.appended</code>, <code>message.completed</code></td><td>Text deltas and finalized assistant messages</td></tr><tr><td>Tools</td><td><code>actions.requested</code>, <code>action.result</code></td><td>Tool names, validated arguments, outputs, and errors</td></tr><tr><td>Approvals</td><td><code>action.approval_requested</code>, <code>action.approval_resolved</code></td><td>A parked tool call and the human decision</td></tr><tr><td>Subagents</td><td><code>subagent.called</code>, <code>subagent.completed</code></td><td>Delegated work</td></tr><tr><td>Artifacts</td><td><code>artifact.tagged</code></td><td>A durable <a href="./artifacts.html">artifact</a> was tagged for this session, by host code or <code>tag_artifact</code></td></tr></tbody></table><p>Pair <code>actions.requested</code> with <code>action.result</code> to reconstruct the tool trajectory. Read <code>turn.completed.data.usage</code> for input, output, and cache token counts. When <code>agent/result.ts</code> is authored, a thrown <code>commit</code>, a <code>ctx.reject</code> that exhausts the two-repair budget, or empty assistant text emits <code>turn.failed</code> instead of <code>turn.completed</code>. <code>ctx.reject(message)</code> re-runs the same turn with that message so the model can revise while tools and the session filesystem are still up.</p><h2 id="how-do-i-stream-or-replay-session-events" tabindex="-1">How do I stream or replay session events? <a class="header-anchor" href="#how-do-i-stream-or-replay-session-events" aria-label="Permalink to &quot;How do I stream or replay session events?&quot;">​</a></h2><p>One endpoint handles both live streaming and replay:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -N</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;http://127.0.0.1:3000/&lt;slug&gt;/v1/session/ses_…/stream?startIndex=0&#39;</span></span></code></pre></div><p>Pass <code>startIndex</code> to continue after the last event you received. Omit it or pass <code>0</code> to replay the full session before following new events. <code>GET /v1/session/:id/events</code> returns a one-time dump without staying connected.</p><p>Event streams replay from disk after a server restart. Conversation state resumes from the Cursor SDK store.</p><h2 id="what-goes-into-a-local-session-workspace" tabindex="-1">What goes into a local session workspace? <a class="header-anchor" href="#what-goes-into-a-local-session-workspace" aria-label="Permalink to &quot;What goes into a local session workspace?&quot;">​</a></h2><p>The Agent SDK creates a workspace before the first local turn:</p><table tabindex="0"><thead><tr><th>Source path</th><th>Lands as</th></tr></thead><tbody><tr><td><code>instructions.*</code></td><td><code>AGENTS.md</code></td></tr><tr><td><code>skills/*</code></td><td><code>.cursor/skills/&lt;name&gt;/SKILL.md</code></td></tr><tr><td>agent tools (<code>execution: &quot;agent&quot;</code>)</td><td>scripts in the session workspace, with a catalog in <code>AGENTS.md</code></td></tr><tr><td><code>sandbox/workspace/**</code></td><td>copied in as seed files</td></tr><tr><td>per-send <code>workspaceFiles</code></td><td>written before the turn</td></tr></tbody></table><p>The local harness uses this workspace as its working directory. Parent directories can contribute <code>AGENTS.md</code> and <code>.cursor</code> settings. Set <code>local.cwd</code> when you need a clean parent directory. A channel can also provide a different working directory for one session, such as a PR worktree.</p><p>See <a href="./agent-config.html#local-cwd">Agent config: local cwd</a> for the inheritance rules.</p><h2 id="where-does-the-agent-sdk-store-session-data" tabindex="-1">Where does the Agent SDK store session data? <a class="header-anchor" href="#where-does-the-agent-sdk-store-session-data" aria-label="Permalink to &quot;Where does the Agent SDK store session data?&quot;">​</a></h2><p>Local state lives under <code>--state-root</code>. Slugged mounts store it under a subdirectory named for the slug.</p><p>Deleting a session directory removes the session from the server: it disappears from listings and can no longer be streamed or continued. Cloud conversations remain on the Cursor backend.</p><p>Nested git checkouts already default <code>local.cwd</code> outside the enclosing repo. See <a href="#what-goes-into-a-local-session-workspace">What goes into a local session workspace?</a>.</p><h2 id="how-do-i-inspect-a-saved-event-stream" tabindex="-1">How do I inspect a saved event stream? <a class="header-anchor" href="#how-do-i-inspect-a-saved-event-stream" aria-label="Permalink to &quot;How do I inspect a saved event stream?&quot;">​</a></h2><p>Use <code>trajectory</code> with a saved trace:</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;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">state-roo</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span></code></pre></div><p>The command prints tool calls, the reply, and token usage in the same JSON shape as <code>run</code>. Use <strong>Open trace</strong> in the playground for a visual view.</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="./http-api.html">HTTP API</a></li><li><a href="./hooks.html">Hooks</a></li></ul>',44)])])}const m=t(n,[["render",d]]);export{u as __pageData,m as default};

package/dist/docs/assets/reference_skills.md.DjQkRefx.js

@@ -1,15 +0,0 @@
-import{_ as e,c as i,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(o,s,h,r,d,p){return t(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to &quot;Skills&quot;">​</a></h1><p>A skill is an on-demand procedure following the <code>SKILL.md</code> convention: the harness advertises each skill by its description, and the model loads the full content only when the task calls for it. Skills are how you give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</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/skills/&lt;name&gt;.md</code></td><td>Flat markdown. Optional <code>description</code> frontmatter; the first body line is the fallback.</td></tr><tr><td><code>agent/skills/&lt;name&gt;/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files (<code>references/…</code>). Requires <code>description</code> frontmatter.</td></tr><tr><td><code>agent/skills/&lt;name&gt;.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@cursor/july/skills</code>.</td></tr></tbody></table><p>Flat markdown:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">description: Use when a pull request needs a structured approval checklist.</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR review checklist</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">1.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Call </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`inspect_pr\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> and confirm required checks passed.</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">2.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Summarize the PR title, author, and remaining risks.</span></span>
-<span class="line"><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">3.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Call </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\`approve_pr\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> only after an explicit request; it requires approval.</span></span></code></pre></div><p>TypeScript, when the content must be generated or carry inline sibling files:</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;"> { defineSkill } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/skills&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;"> defineSkill</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;Research unfamiliar topics before answering.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Gather evidence first, then answer with the key facts.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  files: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;references/checklist.md&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;# Checklist</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">- Find sources.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="how-skills-reach-the-model" tabindex="-1">How skills reach the model <a class="header-anchor" href="#how-skills-reach-the-model" aria-label="Permalink to &quot;How skills reach the model&quot;">​</a></h2><p>On the local runtime, skills land in the session workspace at <code>.cursor/skills/&lt;name&gt;/SKILL.md</code>, and the harness advertises and loads them natively. On the cloud runtime there is no session workspace, so the engine copies the same SKILL.md tree onto an Agent Store for native discovery:</p><ul><li>Hosted deployments write store-root <code>skills/&lt;name&gt;/</code>.</li><li><code>agent-sdk serve</code> / <code>run</code> with a personal <code>CURSOR_API_KEY</code> write namespaced skills on the USER store so they cannot collide with the user&#39;s own skills.</li></ul><p><code>validate</code> still warns about the combination so the store path is visible. Cloud turns with neither a hosted store nor an API key see only skills already in the cloud repo.</p><h2 id="instructions-skills-or-tools" tabindex="-1">Instructions, skills, or tools? <a class="header-anchor" href="#instructions-skills-or-tools" aria-label="Permalink to &quot;Instructions, skills, or tools?&quot;">​</a></h2><p>Instructions are always in context: identity, tool-choice rules, the output contract. Keep them short. Skills load when relevant: procedures, checklists, house style. Reach for a skill when the model needs to <em>follow</em> something but only sometimes needs it loaded. Tools are typed, executable behavior: anything that must be correct every time belongs in tool code, not in prose the model might paraphrase.</p><p>A good skill description is a routing rule, not a title. Say <em>when</em> to use it, like &quot;Use when a pull request needs a structured approval checklist,&quot; because the description is all the model sees before deciding to load it.</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="./instructions.html">Instructions</a>: what stays always-on</li><li><a href="./tools.html">Tools</a>: when prose needs to become code</li><li><a href="./extensions.html">Extensions</a>: skills installed as a package under a namespace</li><li><a href="./project-layout.html">Project layout</a>: where skills sit in the tree</li></ul>`,19)])])}const u=e(n,[["render",l]]);export{c as __pageData,u as default};

package/dist/docs/assets/reference_subagents.md.Dl16gcBj.js

@@ -1,10 +0,0 @@
-import{_ as s,c as a,o as t,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(r,e,l,d,h,p){return t(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to &quot;Subagents&quot;">​</a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one is its own directory under <code>agent/subagents/&lt;id&gt;/</code>, with the same <code>agent.ts</code> + <code>instructions.md</code> shape as the root. On the Cursor harness, subagents run as SDK custom subagents: the parent model delegates through the harness <code>task</code> tool, and the stream records <code>subagent.called</code> and <code>subagent.completed</code>.</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/subagents/researcher/</span></span>
-<span class="line"><span>├── agent.ts            # description (required), model (optional)</span></span>
-<span class="line"><span>└── instructions.md     # the subagent&#39;s own system prompt</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/subagents/researcher/agent.ts</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  description:</span></span>
-<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    &quot;Background research: climate history, records, comparisons across many cities.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
-<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // model: omit to inherit the parent&#39;s model</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="subagent-rules" tabindex="-1">Subagent rules <a class="header-anchor" href="#subagent-rules" aria-label="Permalink to &quot;Subagent rules&quot;">​</a></h2><p><code>description</code> is required. It&#39;s the only thing the parent model reads when deciding whether to delegate, so write it as a routing rule (&quot;Background research: …&quot;), the same discipline as a <a href="./skills.html">skill</a> description. <code>model</code> is optional; omit it to inherit the parent&#39;s model, or set it to run the specialist on a different one.</p><p>Subagents inherit the parent&#39;s execution surface. Every per-subagent capability directory is reported as a warning and ignored: <code>tools/</code>, <code>skills/</code>, <code>mcp-connections/</code> (and the legacy <code>connections/</code> alias), <code>host-connections/</code>, <code>channels/</code>, <code>schedules/</code>, <code>hooks/</code>, <code>sandbox/</code>, and nested <code>subagents/</code>.</p><p>Delegation needs both halves: the description makes it possible, and the parent&#39;s <a href="./instructions.html">instructions</a> make it happen. &quot;When a request needs background research, delegate to the <code>researcher</code> subagent.&quot;</p><h2 id="subagent-or-peer" tabindex="-1">Subagent or peer? <a class="header-anchor" href="#subagent-or-peer" aria-label="Permalink to &quot;Subagent or peer?&quot;">​</a></h2><p>Subagents split one job into roles inside a single agent. When the specialist is independently useful, with its own tools, sessions, and playground, make it a full agent. See <a href="./../guides/agent-to-agent.html#peer-or-subagent">Peer agents</a>.</p><h2 id="patterns" tabindex="-1">Patterns <a class="header-anchor" href="#patterns" aria-label="Permalink to &quot;Patterns&quot;">​</a></h2><p>Fan-out reviews: a PR-approval agent can delegate to two review subagents that read a host-prepared <code>pr/</code> evidence tree and report prioritized findings, which the parent embeds in its approval comment.</p><p>Keep the parent lean: a subagent with focused instructions usually works better than a longer parent prompt with conditional sections. The parent routes; the specialist executes.</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="./skills.html">Skills</a>: when a procedure is enough and a child agent is overkill</li></ul>`,16)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};

package/dist/docs/assets/troubleshooting.md.mnfFG2Em.js

@@ -1 +0,0 @@
-import{_ as t,c as o,o as d,a3 as a}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough.","frontmatter":{"title":"Fix common agent problems","description":"Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."},"headers":[],"relativePath":"troubleshooting.md","filePath":"troubleshooting.md"}'),r={name:"troubleshooting.md"};function s(n,e,i,l,c,h){return d(),o("div",null,[...e[0]||(e[0]=[a('<h1 id="fix-common-agent-problems" tabindex="-1">Fix common agent problems <a class="header-anchor" href="#fix-common-agent-problems" aria-label="Permalink to &quot;Fix common agent problems&quot;">​</a></h1><p>Start with three checks:</p><ol><li>Run <code>agent-sdk validate --dir .</code>.</li><li>Confirm the expected agent and connections in <code>agent-sdk info --dir . --json</code>.</li><li>Reproduce once, then inspect the serve log or session trace.</li></ol><p>Match the visible symptom below. If <code>agent-sdk</code> is not on <code>PATH</code>, use <code>npx @cursor/july</code>.</p><h2 id="serve-or-the-playground-will-not-work" tabindex="-1">Serve or the playground will not work <a class="header-anchor" href="#serve-or-the-playground-will-not-work" aria-label="Permalink to &quot;Serve or the playground will not work&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>serve</code> exits before listening</td><td>Fix the errors from <code>agent-sdk validate --dir .</code>, then start it again.</td></tr><tr><td>Playground is blank or says there are no agents</td><td>Start <code>agent-sdk serve</code>; built playground assets have no agent data without the server.</td></tr><tr><td>Agent-file edits do not appear</td><td>Open the URL printed by <code>serve --dev</code>, then press Enter in its TTY to reload after file changes.</td></tr><tr><td>Sessions exist but the list is empty</td><td>The list is scoped to the authenticated principal. Use the same identity that created the session; a <code>?sessionId=</code> deep link does not bypass authorization.</td></tr><tr><td>The preferred port is busy</td><td>Use the next port printed by the CLI, pass <code>--port &lt;number&gt;</code>, or pass <code>--port 0</code> for any free port.</td></tr></tbody></table><h2 id="a-model-turn-fails" tabindex="-1">A model turn fails <a class="header-anchor" href="#a-model-turn-fails" aria-label="Permalink to &quot;A model turn fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>File reads and greps fail repeatedly with <code>NGHTTP2_FRAME_SIZE_ERROR</code></td><td>Run the agent under Node 22.13 or newer, never Bun.</td></tr><tr><td>The turn immediately reports a missing API key</td><td>Set <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, or run <code>agent-sdk login</code>.</td></tr><tr><td>Login succeeds but the model host rejects the key</td><td>Point login and model traffic at the same API host; check <code>CURSOR_API_BASE_URL</code> and <code>CURSOR_BACKEND_URL</code>.</td></tr><tr><td>Cloud turns cannot reach local tools or skills</td><td>Give the cloud runtime a reachable <code>--public-url</code> and protected tool bridge, or move the required capability into the cloud checkout. See <a href="./reference/agent-config.html#choose-a-runtime">agent runtime</a>.</td></tr></tbody></table><h2 id="a-turn-behaves-unexpectedly" tabindex="-1">A turn behaves unexpectedly <a class="header-anchor" href="#a-turn-behaves-unexpectedly" aria-label="Permalink to &quot;A turn behaves unexpectedly&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Replies quote an ancestor <code>AGENTS.md</code> or unrelated repository rules</td><td>Inspect <code>local.cwd</code> in <code>/v1/info</code>. Set <code>defineAgent({ local: { cwd } })</code> or the session workspace explicitly instead of inheriting the parent checkout.</td></tr><tr><td>The model lists IDE meta-tools but never calls named MCP tools</td><td>Set <code>advertiseTools: true</code> on the local model-visible connection and confirm it under <code>connections</code> in <code>/v1/info</code>.</td></tr><tr><td>Server tools, skills, or seed files are absent</td><td>Check the selected local/cloud runtime and discovered project in <code>/v1/info</code>; follow the capability warning from <code>validate</code>.</td></tr><tr><td><code>validate</code> and <code>run</code> pass but CI type-checking fails</td><td>Run the project type check. Tool results must be JSON-shaped; prefer object literals or <code>type</code> aliases over <code>interface</code> return types.</td></tr></tbody></table><h2 id="http-returns-401-403-or-409" tabindex="-1">HTTP returns 401, 403, or 409 <a class="header-anchor" href="#http-returns-401-403-or-409" aria-label="Permalink to &quot;HTTP returns 401, 403, or 409&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>401</code> outside localhost</td><td>Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only.</td></tr><tr><td><code>403</code> on a stream or follow-up</td><td>Use the same authenticated principal that created the session.</td></tr><tr><td>A localhost route fails through a tunnel or LAN</td><td>Protect the shared host with <code>--bearer-token</code> or authored channel auth. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</td></tr><tr><td><code>409</code> on a follow-up</td><td>Refresh the rotating <code>continuationToken</code> and confirm the target is a chat session; task sessions do not accept follow-ups.</td></tr><tr><td><code>409 session_busy</code> from <code>call --session</code></td><td>Wait for the turn, omit <code>--session</code>, or mark a read-only tool with <code>effect: &quot;read&quot;</code> so it can run concurrently.</td></tr><tr><td>A custom route fails schema type-checking</td><td>Add the required Zod <code>querySchema</code> for <code>GET</code>, or <code>bodySchema</code> for <code>POST</code>, <code>PUT</code>, and <code>PATCH</code>. See <a href="./reference/channels.html">Channels</a>.</td></tr></tbody></table><h2 id="a-hosted-deployment-fails-or-looks-stale" tabindex="-1">A hosted deployment fails or looks stale <a class="header-anchor" href="#a-hosted-deployment-fails-or-looks-stale" aria-label="Permalink to &quot;A hosted deployment fails or looks stale&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Local changes do not appear after deploy</td><td><code>deploy</code> reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again.</td></tr><tr><td>The deployment never becomes running</td><td>Run <code>agent-sdk deployment &lt;slug&gt;</code> and <code>agent-sdk logs --prod --slug &lt;slug&gt;</code>, then act on the reported build or startup error.</td></tr><tr><td>A secret or egress change has no effect</td><td>Confirm the name with <code>secrets list</code>, verify the <code>hosting</code> block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy.</td></tr><tr><td>Cursor events stopped after redeploy</td><td>Redeploy replaces CLI-supplied event repositories. Pass every <code>--cursor-events-repo</code> value again.</td></tr><tr><td>External HTTP rejects the alias token</td><td>Update the caller with the current token. If the token is lost or exposed, run <code>agent-sdk rotate-token &lt;slug&gt;</code> and replace it everywhere.</td></tr></tbody></table><p>See <a href="./deployment.html">Deployment</a> for source, credential, and redeployment boundaries.</p><h2 id="github-deliveries-fail" tabindex="-1">GitHub deliveries fail <a class="header-anchor" href="#github-deliveries-fail" aria-label="Permalink to &quot;GitHub deliveries fail&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>github forward</code> returns 401 on every delivery after creating the hook</td><td>Clear <code>GITHUB_TOKEN</code> and <code>GH_TOKEN</code> for that command so the forwarder uses the <code>gh</code> CLI login: <code>GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...</code>.</td></tr><tr><td><code>Hook already exists</code></td><td>Run one forwarder for the repository and stop the stale process.</td></tr><tr><td>Direct webhook deliveries are rejected outside <code>--dev</code></td><td>Configure the same <code>GITHUB_WEBHOOK_SECRET</code> on the signer and server. Cursor event pull needs no public webhook or webhook secret.</td></tr><tr><td>You cannot create a forwarder</td><td>Use <code>agent-sdk github replay &lt;pr-url&gt;</code>; it needs pull access instead of repository administration.</td></tr></tbody></table><p>The <a href="./guides/github.html">GitHub guide</a> covers event pull, replay, and direct webhooks.</p><h2 id="slack-does-not-respond" tabindex="-1">Slack does not respond <a class="header-anchor" href="#slack-does-not-respond" aria-label="Permalink to &quot;Slack does not respond&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Logs say <code>channel idle ... missing credentials</code></td><td>Run <code>agent-sdk slack create --dir &lt;agent&gt;</code>, then check the generated prefix with <code>agent-sdk slack doctor</code>. Use <code>slack init --manual</code> only for an app you own.</td></tr><tr><td><code>slack create</code> is waiting for workspace approval</td><td>Open the approval link printed by the CLI, keep the command running, and retry after an admin approves.</td></tr><tr><td>The bot ignores ordinary channel posts</td><td>Configure <code>engagement.channelPosts</code>, create the app with <code>--channel-posts</code>, and invite it to every allowed channel.</td></tr><tr><td>Approval buttons do nothing</td><td>Set <code>toolApprovals: true</code>, then recreate the app if its interactivity is not enabled.</td></tr></tbody></table><p>See the <a href="./guides/slack.html">Slack guide</a> for app setup and engagement choices.</p><h2 id="mcp-authorization-fails" tabindex="-1">MCP authorization fails <a class="header-anchor" href="#mcp-authorization-fails" aria-label="Permalink to &quot;MCP authorization fails&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td><code>must be defineConnection({ url, oauth: true })</code></td><td>Add <code>oauth: true</code> to the named URL connection or correct the connection filename passed to <code>mcp oauth</code>.</td></tr><tr><td>Local auth works but hosted calls return unauthorized</td><td>Complete Connect for the running process, or run <code>mcp oauth &lt;name&gt; --store</code> and redeploy for future replacements.</td></tr><tr><td>The model invents <code>mcp_auth</code> instead of calling the server</td><td>Set <code>advertiseTools: true</code> for named local tools, or expose a host-side wrapper through <code>ctx.host.mcp</code>.</td></tr></tbody></table><p>See <a href="./guides/mcp-oauth.html">Host MCP OAuth</a> for the credential lifecycle.</p><h2 id="schedules-reminders-or-approvals-stall" tabindex="-1">Schedules, reminders, or approvals stall <a class="header-anchor" href="#schedules-reminders-or-approvals-stall" aria-label="Permalink to &quot;Schedules, reminders, or approvals stall&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A schedule or reminder never fires under <code>--dev</code></td><td>Trigger it through the matching <code>/v1/dev/schedules/&lt;id&gt;</code> or <code>/v1/dev/reminders/&lt;id&gt;</code> route; development mode does not auto-fire.</td></tr><tr><td>A pending approval disappears after restart</td><td>Parked approvals do not survive restart. Run the turn again.</td></tr><tr><td>A reminder is disarmed with <code>handler_lost_on_restart</code></td><td>Recreate handler-form reminders after restart, or use a prompt-form reminder.</td></tr><tr><td>The same schedule fires on several self-hosted processes</td><td>Enable schedules on one serving process per project and pass <code>--no-schedules</code> to the others.</td></tr></tbody></table><h2 id="a-credential-was-exposed" tabindex="-1">A credential was exposed <a class="header-anchor" href="#a-credential-was-exposed" aria-label="Permalink to &quot;A credential was exposed&quot;">​</a></h2><table tabindex="0"><thead><tr><th>What you see</th><th>What to do</th></tr></thead><tbody><tr><td>A secret value appears in a command, transcript, or shell history</td><td>Rotate it at the provider, set it again through hidden input or stdin, and test the feature.</td></tr><tr><td>An alias token appears outside its secure destination</td><td>Run <code>agent-sdk rotate-token &lt;slug&gt;</code>, store the new value outside transcripts, and update every caller.</td></tr><tr><td>Someone printed a secret to verify it</td><td>Rotate it. Confirm only the name with <code>agent-sdk secrets list &lt;slug&gt;</code>, then redeploy and exercise the feature.</td></tr></tbody></table><h2 id="read-the-session-trace" tabindex="-1">Read the session trace <a class="header-anchor" href="#read-the-session-trace" aria-label="Permalink to &quot;Read the session trace&quot;">​</a></h2><p>Start with <code>actions.requested</code> and <code>action.result</code>. Count calls by tool name, pair every request with its result, and separate host preparation from tools chosen by the model.</p><p><code>turn.failed</code> with <code>turn interrupted</code> usually means a follow-up or stop ended the turn deliberately. Other failures should have an error event near the tool or model boundary that produced them.</p><p>Use the trace path printed by <code>agent-sdk run</code>:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">trace-pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><p>The playground&#39;s <strong>Open trace</strong> control renders the same trajectory. When the agent runs but makes poor decisions, move from diagnosis to a measured <a href="./hillclimbing.html">hillclimb</a>.</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="./deployment.html">Deployment</a>: hosted and self-hosted boundaries</li><li><a href="./reference/sessions.html">Sessions</a>: session ownership and event vocabulary</li><li><a href="./reference/cli.html">CLI reference</a>: command flags and exit behavior</li></ul>',36)])])}const m=t(r,[["render",s]]);export{u as __pageData,m as default};