@cursor/july 0.1.10 → 0.1.11

package/dist/docs/assets/{index.md.COiu-1jL.js → index.md.t0TM2Qzz.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function r(o,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="agentkit-documentation" tabindex="-1">agentkit documentation <a class="header-anchor" href="#agentkit-documentation" aria-label="Permalink to &quot;agentkit documentation&quot;">​</a></h1><p>agentkit helps you build your own software factory: agents that inspect builds, review pull requests, gate promotions, and wake from Slack or GitHub when work arrives. You author each agent as ordinary files in a TypeScript project under <code>agent/</code>: markdown for agent instruction prompts, TypeScript for typed behavior. The framework discovers those files, and serves the agent over channels. The Cursor SDK and the Cursor harness run the turns.</p><p>You write the tools, instructions, channels, and evals. In return you get a factory you can version, test, and ship: side effects stay behind human approvals, and every change stays regression-checked.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-agent/</span></span>
+import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function o(r,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="agentkit-documentation" tabindex="-1">agentkit documentation <a class="header-anchor" href="#agentkit-documentation" aria-label="Permalink to &quot;agentkit documentation&quot;">​</a></h1><p>agentkit helps you build your own software factory: agents that inspect builds, review pull requests, gate promotions, and wake from Slack or GitHub when work arrives. You author each agent as ordinary files in a TypeScript project under <code>agent/</code>: markdown for agent instruction prompts, TypeScript for typed behavior. The framework discovers those files, and serves the agent over channels. The Cursor SDK and the Cursor harness run the turns.</p><p>You write the tools, instructions, channels, and evals. In return you get a factory you can version, test, and ship: side effects stay behind human approvals, and every change stays regression-checked.</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, local/cloud runtime</span></span>
@@ -14,7 +14,7 @@ import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g
 <span class="line"><span>│   ├── schedules/           # cron-driven runs</span></span>
 <span class="line"><span>│   ├── sandbox/workspace/   # files seeded into each session workspace</span></span>
 <span class="line"><span>│   └── lib/                 # shared code (import-only, never discovered)</span></span>
-<span class="line"><span>└── evals/                   # filesystem evals (regression checks)</span></span></code></pre></div><p>Every running serve host also mounts this documentation at <code>/docs</code> (disable it with <code>--no-docs</code>).</p><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><p>Pick your entry point based on your goal.</p><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to agentkit</td><td><a href="./quickstart.html">Quickstart</a> (PR approver), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="the-documentation" tabindex="-1">The documentation <a class="header-anchor" href="#the-documentation" aria-label="Permalink to &quot;The documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR approver that reviews by complexity and wakes from webhooks.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./concepts.html">Concepts</a>: the mental model behind the framework.</li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: make an agent better one measured round at a time.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: wake the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare all eleven agents by runtime, channels, tools, state, and architecture.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/fsd.html">Remote PR coordinator</a>: hand PR triage from local chat and webhooks to durable remote sessions.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: symptom to cause, in plain language.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>The docs write commands as <code>agentkit &lt;command&gt;</code>. Where that command comes from depends on where you run.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>When running from a source checkout there is no installed bin. Alias it from the package directory:</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:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> packages/agent-serve</span></span>
+<span class="line"><span>└── evals/                   # filesystem evals (regression checks)</span></span></code></pre></div><p>Every running serve host also mounts this documentation at <code>/docs</code> (disable it with <code>--no-docs</code>).</p><h2 id="where-to-start" tabindex="-1">Where to start <a class="header-anchor" href="#where-to-start" aria-label="Permalink to &quot;Where to start&quot;">​</a></h2><p>Pick your entry point based on your goal.</p><table tabindex="0"><thead><tr><th>You are...</th><th>Start with</th></tr></thead><tbody><tr><td>New to agentkit</td><td><a href="./quickstart.html">Quickstart</a> (PR approver), then <a href="./concepts.html">Concepts</a></td></tr><tr><td>Building a new agent with Cursor</td><td><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></td></tr><tr><td>Learning from working agents</td><td><a href="./example-agents/">Example agents</a></td></tr><tr><td>Wiring an agent to Slack</td><td><a href="./guides/slack.html">Slack guide</a></td></tr><tr><td>Wiring an agent to GitHub webhooks</td><td><a href="./guides/github.html">GitHub guide</a></td></tr><tr><td>Making an existing agent measurably better</td><td><a href="./evals.html">Evals</a>, then <a href="./hillclimbing.html">Hillclimbing</a></td></tr><tr><td>Comparing variants on live traffic</td><td><a href="./ab.html">Live A/B metrics</a></td></tr><tr><td>Deploying with Cursor or on your own infrastructure</td><td><a href="./deployment.html">Deployment</a></td></tr><tr><td>Debugging something that misbehaves</td><td><a href="./troubleshooting.html">Fix common agent problems</a></td></tr></tbody></table><h2 id="the-documentation" tabindex="-1">The documentation <a class="header-anchor" href="#the-documentation" aria-label="Permalink to &quot;The documentation&quot;">​</a></h2><p><strong>Core</strong></p><ul><li><a href="./quickstart.html">Quickstart</a>: build a PR approver that reviews by complexity and wakes from webhooks.</li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a>: use the bundled skill for a guided build.</li><li><a href="./concepts.html">Concepts</a>: the mental model behind the framework.</li></ul><p><strong>Self-improving Agents</strong></p><ul><li><a href="./building-with-agents.html">Building agents with agents</a>: use a coding agent to scaffold, run, and iterate on your agent.</li><li><a href="./evals.html">Evals</a>: author <code>defineEval</code> cases, pick fixtures, and use evals as regression checks.</li><li><a href="./ab.html">Live A/B metrics</a>: assign sticky variants and compare cumulative metrics on live sessions.</li><li><a href="./hillclimbing.html">Hillclimbing</a>: make an agent better one measured round at a time.</li></ul><p><strong>Guides</strong></p><ul><li><a href="./guides/webhooks.html">Webhooks and custom channels</a>: give the agent its own HTTP surface.</li><li><a href="./guides/github.html">GitHub</a>: wake the agent from pull requests, CI, and comments.</li><li><a href="./guides/slack.html">Slack</a>: put the agent in Slack over Socket Mode.</li><li><a href="./guides/human-in-the-loop.html">Human-in-the-loop approvals</a>: park a tool call until a person signs off.</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: authorize <code>oauth: true</code> connections, store tokens locally, and <code>--store</code> them on hosted deployments.</li><li><a href="./guides/agent-to-agent.html">Agent-to-agent</a>: every agent is an MCP server; agents can delegate to each other.</li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a>: run turns on Cursor cloud agents instead of the local harness.</li></ul><p><strong>Example agents</strong></p><ul><li><a href="./example-agents/">Choose the right example</a>: compare all eleven agents by runtime, channels, tools, state, and architecture.</li><li><a href="./example-agents/weather-agent.html">Weather agent</a>: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.</li><li><a href="./example-agents/slack-agent.html">Slack agent</a>: put a minimal agent in Slack through an account-linked transport.</li><li><a href="./example-agents/concierge.html">Concierge</a>: delegate work to a peer agent with its own context and sessions.</li><li><a href="./example-agents/benny.html">Playbook router</a>: route Slack intake through inherited repository playbooks.</li><li><a href="./example-agents/bugbot.html">PR evidence reviewer</a>: review a host-prepared, diff-first pull-request evidence tree.</li><li><a href="./example-agents/approval-buddy.html">Approval Buddy</a>: keep approval policy in code while subagents supply review findings.</li><li><a href="./example-agents/security-reviewer.html">Security Reviewer</a>: run a staged, parallel security pipeline with live playground progress.</li><li><a href="./example-agents/fsd.html">Remote PR coordinator</a>: hand PR triage from local chat and webhooks to durable remote sessions.</li><li><a href="./example-agents/knowledge-base.html">Knowledge base</a>: turn conversations about people, systems, decisions, and preferences into shared markdown.</li><li><a href="./example-agents/codebase-wiki.html">Codebase wiki</a>: ingest merged PRs into per-feature pages with a daily digest schedule.</li><li><a href="./example-agents/codeowners-review.html">Codeowners review</a>: route PR reviews by ownership to per-area playbooks and aggregate verdicts.</li></ul><p><strong>Operating</strong></p><ul><li><a href="./deployment.html">Deployment</a>: Cursor-managed hosting, self-hosting, auth, state, and operations.</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: symptom to cause, in plain language.</li></ul><p><strong>Reference</strong></p><ul><li><a href="./reference/project-layout.html">Project layout</a>: the full folder structure.</li><li><a href="./reference/agent-config.html">Agent config</a> · <a href="./reference/instructions.html">Instructions</a> · <a href="./reference/tools.html">Tools</a> · <a href="./reference/prompt.html"><code>prompt</code></a> · <a href="./reference/skills.html">Skills</a> · <a href="./reference/connections.html">MCP connections</a> · <a href="./reference/subagents.html">Subagents</a></li><li><a href="./reference/channels.html">Channels</a> · <a href="./reference/schedules.html">Schedules and reminders</a> · <a href="./reference/hooks.html">Hooks</a> · <a href="./reference/sessions.html">Sessions and streaming</a> · <a href="./reference/playground.html">Playground</a></li><li><a href="./reference/cli.html">CLI</a> · <a href="./reference/http-api.html">HTTP API</a></li></ul><h2 id="run-the-cli" tabindex="-1">Run the CLI <a class="header-anchor" href="#run-the-cli" aria-label="Permalink to &quot;Run the CLI&quot;">​</a></h2><p>The docs write commands as <code>agentkit &lt;command&gt;</code>. Where that command comes from depends on where you run.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>When running from a source checkout there is no installed bin. Alias it from the package directory:</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:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> packages/agent-serve</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">alias</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> agentkit</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;pnpm exec tsx </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PWD</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/src/bin/agent-serve.ts&quot;</span></span></code></pre></div><p>When <code>@cursor/july</code> is installed as a dependency, the <code>agentkit</code> bin is on your package manager&#39;s path (<code>pnpm exec agentkit</code>, <code>npx agentkit</code>).</p></div><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The framework is being renamed from agent-serve to agentkit, and CLI examples use the new <code>agentkit</code> name. Paths, package imports, and environment variables keep their current names until the code rename ships:</p><table tabindex="0"><thead><tr><th>Docs say</th><th>Current name</th></tr></thead><tbody><tr><td><code>@cursor/july</code> imports and dependency</td><td><code>@cursor/july</code></td></tr><tr><td><code>agentkit</code> bin</td><td><code>agent-serve</code></td></tr><tr><td><code>dist/bin/agentkit.js</code></td><td><code>dist/bin/agent-serve.js</code></td></tr><tr><td><code>.agentkit/</code> state directory</td><td><code>.agent-serve/</code></td></tr><tr><td><code>/var/lib/agentkit</code> (deploy state root)</td><td><code>/var/lib/agent-serve</code></td></tr><tr><td><code>CURSOR_AGENT_KIT_*</code> env vars</td><td><code>AGENT_SERVE_*</code></td></tr><tr><td><code>agentkit (&lt;hostname&gt;)</code> API key name</td><td><code>agent-serve (&lt;hostname&gt;)</code></td></tr><tr><td>Package path <code>packages/agentkit</code></td><td><code>packages/agent-serve</code></td></tr><tr><td>Package skills <code>packages/agentkit/skills/</code></td><td><code>packages/agent-serve/skills/</code></td></tr></tbody></table></div><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p>Run agentkit with Node 22.13 or newer, and never with Bun. Bun&#39;s HTTP/2 client corrupts the Cursor SDK&#39;s tool-result streams (<code>NGHTTP2_FRAME_SIZE_ERROR</code>), so every built-in read or grep the model makes fails and turns degrade into minutes-long retry loops.</p></div><h2 id="credentials" tabindex="-1">Credentials <a class="header-anchor" href="#credentials" aria-label="Permalink to &quot;Credentials&quot;">​</a></h2><p>Model turns run on the Cursor harness, so the serving host needs a Cursor credential. Sign in once, or export an API key:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">          # browser sign-in; mints + stores a revocable API key</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># or: export CURSOR_API_KEY=key_...</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">         # which account powers this host, and why</span></span></code></pre></div><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><p>These docs describe behavior. The package <a href="./../README.html"><code>README.md</code></a> is the compact reference, and <a href="./../AGENTS.html"><code>AGENTS.md</code></a> is the coding-agent cheat sheet. Task-shaped guides that ship with the package live under <a href="./../skills/"><code>skills/</code></a>; point a coding agent working on a agentkit project at them first. When the docs and the code disagree, the code is authoritative. Fix the doc.</p>`,31)])])}const u=a(i,[["render",r]]);export{g as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> whoami</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">         # which account powers this host, and why</span></span></code></pre></div><h2 id="related-documentation" tabindex="-1">Related documentation <a class="header-anchor" href="#related-documentation" aria-label="Permalink to &quot;Related documentation&quot;">​</a></h2><p>These docs describe behavior. The package <a href="./../README.html"><code>README.md</code></a> is the compact reference, and <a href="./../AGENTS.html"><code>AGENTS.md</code></a> is the coding-agent cheat sheet. Task-shaped guides that ship with the package live under <a href="./../skills/"><code>skills/</code></a>; point a coding agent working on a agentkit project at them first. When the docs and the code disagree, the code is authoritative. Fix the doc.</p>`,31)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};

package/dist/docs/assets/{index.md.COiu-1jL.lean.js → index.md.t0TM2Qzz.lean.js}

@@ -1 +1 @@
-import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function r(o,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n("",31)])])}const u=a(i,[["render",r]]);export{g as __pageData,u as default};
+import{_ as a,c as t,o as s,ag as n}from"./chunks/framework.CAZyNGu9.js";const g=JSON.parse('{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals.","frontmatter":{"title":"agentkit documentation","description":"Build your own software factory with Cursor agents as ordinary files: tools, approvals, channels, and evals."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function o(r,e,l,d,h,c){return s(),t("div",null,[...e[0]||(e[0]=[n("",31)])])}const u=a(i,[["render",o]]);export{g as __pageData,u as default};

package/dist/docs/assets/{reference_cli.md.CjfiV2Q-.js → reference_cli.md.B74NrVzb.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>agentkit</code> and the legacy <code>agent-serve</code> alias. The examples on this page use <code>agentkit</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p>The current release still uses <code>.agent-serve</code> for on-disk state. See the <a href="./../README.html#run-the-cli">rename table</a> for identifiers still moving to agentkit names.</p><p><code>agentkit help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agentkit slack help</code> and <code>agentkit github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved <code>events.ndjson</code> file</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login--logout--whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Set up and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, agentkit selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="cli-reference" tabindex="-1">CLI reference <a class="header-anchor" href="#cli-reference" aria-label="Permalink to &quot;CLI reference&quot;">​</a></h1><p><code>@cursor/july</code> installs <code>agentkit</code> and the legacy <code>agent-serve</code> alias. The examples on this page use <code>agentkit</code>. Run the CLI with Node 22.13 or newer. Don&#39;t run it with Bun; Bun corrupts tool-result streams from the Cursor SDK.</p><p>The current release still uses <code>.agent-serve</code> for on-disk state. See the <a href="./../README.html#run-the-cli">rename table</a> for identifiers still moving to agentkit names.</p><p><code>agentkit help</code> prints the built-in summary. The Slack and GitHub packs also provide <code>agentkit slack help</code> and <code>agentkit github help</code>.</p><table tabindex="0"><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Start local development with <code>serve --dev</code></td></tr><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent</td></tr><tr><td><a href="#resume"><code>resume</code></a></td><td>Reattach chat to a previous session</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow local or hosted logs</td></tr><tr><td><a href="#sessions"><code>sessions</code></a></td><td>List sessions on a running agent</td></tr><tr><td><a href="#session"><code>session</code></a></td><td>Inspect one session</td></tr><tr><td><a href="#playground"><code>playground</code></a></td><td>Open the local or hosted playground</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run one or more turns locally, remotely, or on a hosted agent</td></tr><tr><td><a href="#call"><code>call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run filesystem evals</td></tr><tr><td><a href="#trajectory"><code>trajectory</code></a></td><td>Summarize a saved <code>events.ndjson</code> file</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or print the setup guide</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print the discovered agent surface</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check a project and fail on errors</td></tr><tr><td><a href="#login--logout--whoami"><code>login</code> / <code>logout</code> / <code>whoami</code></a></td><td>Manage the host&#39;s Cursor credential</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy one or more agents to Cursor managed hosting</td></tr><tr><td><a href="#deployments"><code>deployments</code></a></td><td>List hosted deployments</td></tr><tr><td><a href="#deployment"><code>deployment</code></a></td><td>Inspect one hosted deployment</td></tr><tr><td><a href="#stop"><code>stop</code></a></td><td>Stop a hosted deployment</td></tr><tr><td><a href="#rotate-token"><code>rotate-token</code></a></td><td>Replace a deployment&#39;s alias token</td></tr><tr><td><a href="#rotate-pod-credential"><code>rotate-pod-credential</code></a></td><td>Replace a deployment&#39;s pod credential</td></tr><tr><td><a href="#secrets"><code>secrets</code></a></td><td>Manage deployment secrets</td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize host MCP OAuth; optional <code>--store</code> to deployment secrets</td></tr><tr><td><a href="#slack"><code>slack ...</code></a></td><td>Set up and check Slack channels</td></tr><tr><td><a href="#github"><code>github ...</code></a></td><td>Forward, replay, and inspect GitHub webhook channels</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Choose a target <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Choose a target&quot;">​</a></h2><p>Request-sending commands support three target types.</p><table tabindex="0"><thead><tr><th>Target</th><th>How to select it</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code>, unless the command uses the localhost default described next</td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code></td></tr><tr><td>Cursor managed hosting</td><td>Pass <code>--prod</code></td><td><code>chat</code>, <code>resume</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, <code>playground</code>, <code>run</code>, <code>call</code>, <code>eval</code></td></tr></tbody></table><p><code>chat</code>, <code>logs</code>, <code>sessions</code>, <code>session</code>, and <code>playground</code> default to <code>http://127.0.0.1:3000</code>. A <code>--url</code> must include the agent slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. <code>--slug</code> doesn&#39;t change an explicit URL.</p><p>With <code>--prod</code>, <code>--slug</code> selects the deployment and <code>--team</code> selects the Cursor team. The slug defaults to the <code>--dir</code> basename. The team defaults to the signed-in account&#39;s team. <code>--url</code> and <code>--prod</code> are mutually exclusive.</p><p>Use <code>--bearer-token &lt;token&gt;</code> when a running server requires bearer authentication. Hosted commands use your Cursor credential to request short-lived engine access. <code>--api-key</code> overrides the Cursor credential for <code>login</code>, <code>serve</code>, hosted targets, and managed-hosting commands. <code>--state-root</code> applies to <code>serve</code> and ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> servers. Running and hosted targets ignore it.</p><p>For ephemeral <code>run</code>, <code>call</code>, and <code>eval</code> commands, omitting <code>--slug</code> selects an unslugged root mount when one exists. Otherwise, agentkit selects the first discovered agent.</p><h2 id="serve" tabindex="-1">serve <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;serve&quot;">​</a></h2><p><code>serve</code> hosts every agent under <code>--dir</code> in multi-agent mode by default.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--port </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">3000]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--host </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">127.0.0.1]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dev]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--mode multi</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">single] [--api-key </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--state-root </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--bearer-token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> --allow-anonymous]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                  [--allow-anonymous-cursor-github]</span></span>
@@ -42,7 +42,7 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> logout</span></span></code></pre></div><p><code>login</code> signs the host in to Cursor: browser sign-in mints a named, dashboard-revocable API key, and only the key is stored (the default name is <code>&lt;invoked command&gt; (&lt;hostname&gt;)</code>). It powers inference, the cloud runtime, and Cursor account MCP connections. <code>--key-name</code> changes the name of a browser-minted key. <code>login --api-key</code> validates and stores a key you already created.</p><p><code>whoami</code> shows which credential is active and why. <code>CURSOR_API_KEY</code> takes precedence over the stored login. <code>logout</code> removes the local credential file but doesn&#39;t revoke the API key. Revoke it in the Cursor dashboard when it should stop working.</p><p>Non-production backends: login and account RPCs honor <code>CURSOR_API_BASE_URL</code> while the SDK harness honors <code>CURSOR_BACKEND_URL</code>. Set both to the same URL, or keys minted on one backend are rejected by the other.</p><h2 id="update" tabindex="-1">update <a class="header-anchor" href="#update" aria-label="Permalink to &quot;update&quot;">​</a></h2><p><code>update</code> upgrades an installed copy to the latest published version.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> update</span></span></code></pre></div><p>The command checks npm&#39;s <code>latest</code> tag, detects how agentkit was installed, and runs the matching npm, pnpm, Yarn, or Bun upgrade command. It handles global installs and project dependencies. It doesn&#39;t prompt before running the package-manager command.</p><p>Source checkouts, <code>npx</code> or <code>pnpm dlx</code> caches, and unknown install layouts aren&#39;t changed. The command prints a manual upgrade hint instead.</p><p>Published installs also check for a newer version at most once every 24 hours and print an update warning on stderr. Source checkouts, CI, and commands with an explicit <code>--json</code> flag skip this automatic check.</p><h2 id="deploy" tabindex="-1">deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;deploy&quot;">​</a></h2><p><code>deploy</code> sends one or more agents to Cursor managed hosting.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--slug </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:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> --all]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--repo </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https-url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--ref </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">git-ref</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--path </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">agent-path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--cursor-events-repo owner/name]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--allow-domain </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">domain</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires team-admin permission and the team&#39;s cloud-agent entitlement. <code>--team</code> defaults to the signed-in account&#39;s team.</p><p>For a single project, the slug defaults to a normalized version of the directory name. Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, with a maximum of 64 characters. For a directory with several agents, select one with <code>--slug</code>, deploy all with <code>--all</code>, or choose from the TTY prompt. Non-interactive callers must pass <code>--slug</code> or <code>--all</code>. If <code>--dir</code> contains no agent project or child agents, <code>deploy</code> creates a static placeholder using <code>--slug</code> or a slug derived from the directory name. In this case, <code>--all</code> fails.</p><p>The command infers <code>--repo</code>, <code>--ref</code>, and <code>--path</code> from the current Git checkout when possible. Explicit flags take precedence. <code>--repo</code> must use HTTPS. Repeat <code>--cursor-events-repo</code> to select SCM event sources. Repeat <code>--allow-domain</code> to add engine egress domains; these values are combined with <code>hosting.egressDomains</code> from the agent config. Egress domains apply only to repository-backed deployments. Each domain must be a lowercase hostname with at least two labels and an alphabetic top-level domain. One leading <code>*.</code> wildcard is allowed. A deployment can declare at most 20 domains.</p><p>By default, the command polls every three seconds for up to ten minutes and succeeds only when the deployment reaches <code>running</code>. <code>--no-wait</code> returns after the deployment request is accepted. Multi-agent deploys run sequentially. When several agents are selected, <code>--path</code> is ignored and each project infers its own path. A single-target <code>--json</code> run prints one object; a multi-target run prints an array.</p><p>The first deployment can return an alias token. It appears once in text or JSON output and can&#39;t be retrieved later. Store it as a secret. Send it as <code>X-Agent-Alias-Token</code> when calling the stable alias URL, or use it to sign in to the hosted playground.</p><p>See <a href="./../deployment.html">Deployment</a> for the hosting security model and state layout.</p><h2 id="deployments" tabindex="-1">deployments <a class="header-anchor" href="#deployments" aria-label="Permalink to &quot;deployments&quot;">​</a></h2><p><code>deployments</code> lists the selected team&#39;s deployments.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployments</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output shows each slug, status, generation, deployment kind, and update time. <code>--json</code> prints <code>{ deployments }</code>.</p><h2 id="deployment" tabindex="-1">deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;deployment&quot;">​</a></h2><p><code>deployment</code> prints the full status of one deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output includes status, generation, kind, alias, source, egress domains, secret names, engine state, and the last error when present. <code>--json</code> returns the full API response. It can include short-lived <code>engineAccess.headers</code>, so handle JSON output as a credential.</p><h2 id="stop" tabindex="-1">stop <a class="header-anchor" href="#stop" aria-label="Permalink to &quot;stop&quot;">​</a></h2><p><code>stop</code> shuts down a deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> stop</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command polls for up to ten minutes until the status reaches <code>stopped</code>. <code>--no-wait</code> returns after the stop request is accepted.</p><h2 id="rotate-token" tabindex="-1">rotate-token <a class="header-anchor" href="#rotate-token" aria-label="Permalink to &quot;rotate-token&quot;">​</a></h2><p><code>rotate-token</code> replaces the alias token used by callers and the hosted playground.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-token</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement is shown once. <code>--json</code> prints <code>{ aliasToken }</code>.</p><h2 id="rotate-pod-credential" tabindex="-1">rotate-pod-credential <a class="header-anchor" href="#rotate-pod-credential" aria-label="Permalink to &quot;rotate-pod-credential&quot;">​</a></h2><p><code>rotate-pod-credential</code> replaces the credential used by the running engine pod.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-pod-credential</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The command returns only the masked key and revokes the old credential immediately. Redeploy at once to inject the replacement; the current pod can&#39;t authenticate to Cursor in between.</p><h2 id="secrets" tabindex="-1">secrets <a class="header-anchor" href="#secrets" aria-label="Permalink to &quot;secrets&quot;">​</a></h2><p><code>secrets</code> manages environment secrets for a deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</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;"> NAME[=VALUE]...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">                [--allow-domain </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">domain</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires team-admin permission and the team&#39;s cloud-agent entitlement. <code>--team</code> defaults to the signed-in account&#39;s team.</p><p>For a single project, the slug defaults to a normalized version of the directory name. Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, with a maximum of 64 characters. For a directory with several agents, select one with <code>--slug</code>, deploy all with <code>--all</code>, or choose from the TTY prompt. Non-interactive callers must pass <code>--slug</code> or <code>--all</code>. If <code>--dir</code> contains no agent project or child agents, <code>deploy</code> creates a static placeholder using <code>--slug</code> or a slug derived from the directory name. In this case, <code>--all</code> fails.</p><p>The command infers <code>--repo</code>, <code>--ref</code>, and <code>--path</code> from the current Git checkout when possible. Explicit flags take precedence. <code>--repo</code> must use HTTPS. Repeat <code>--cursor-events-repo</code> to select SCM event sources. Repeat <code>--allow-domain</code> to add engine egress domains; these values are combined with <code>hosting.egressDomains</code> from the agent config. Egress domains apply only to repository-backed deployments. Each domain must be a lowercase hostname with at least two labels and an alphabetic top-level domain. One leading <code>*.</code> wildcard is allowed. A deployment can declare at most 20 domains.</p><p>By default, the command polls every three seconds for up to ten minutes and succeeds only when the deployment reaches <code>running</code>. <code>--no-wait</code> returns after the deployment request is accepted. Multi-agent deploys run sequentially. When several agents are selected, <code>--path</code> is ignored and each project infers its own path. A single-target <code>--json</code> run prints one object; a multi-target run prints an array.</p><p>The first deployment can return an alias token. It appears once in text or JSON output and can&#39;t be retrieved later. Store it as a secret. Send it as <code>X-Agent-Alias-Token</code> when calling the stable alias URL, or use it to sign in to the hosted playground.</p><p>See <a href="./../deployment.html">Deployment</a> for the hosting security model and state layout.</p><h2 id="deployments" tabindex="-1">deployments <a class="header-anchor" href="#deployments" aria-label="Permalink to &quot;deployments&quot;">​</a></h2><p><code>deployments</code> lists the selected team&#39;s deployments.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployments</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output shows each slug, status, generation, deployment kind, and update time. <code>--json</code> prints <code>{ deployments }</code>.</p><h2 id="deployment" tabindex="-1">deployment <a class="header-anchor" href="#deployment" aria-label="Permalink to &quot;deployment&quot;">​</a></h2><p><code>deployment</code> prints the full status of one deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deployment</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Text output includes status, generation, kind, alias, source, egress domains, secret names, engine state, and the last error when present. <code>--json</code> returns the full API response. It can include short-lived <code>engineAccess.headers</code>, so handle JSON output as a credential.</p><h2 id="stop" tabindex="-1">stop <a class="header-anchor" href="#stop" aria-label="Permalink to &quot;stop&quot;">​</a></h2><p><code>stop</code> shuts down a deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> stop</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--no-wait] [--json]</span></span></code></pre></div><p>The command polls for up to ten minutes until the status reaches <code>stopped</code>. <code>--no-wait</code> returns after the stop request is accepted.</p><h2 id="rotate-token" tabindex="-1">rotate-token <a class="header-anchor" href="#rotate-token" aria-label="Permalink to &quot;rotate-token&quot;">​</a></h2><p><code>rotate-token</code> replaces the alias token used by callers and the hosted playground.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-token</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement is shown once. <code>--json</code> prints <code>{ aliasToken }</code>.</p><h2 id="rotate-pod-credential" tabindex="-1">rotate-pod-credential <a class="header-anchor" href="#rotate-pod-credential" aria-label="Permalink to &quot;rotate-pod-credential&quot;">​</a></h2><p><code>rotate-pod-credential</code> replaces the credential used by the running engine pod.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rotate-pod-credential</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>The command returns only the masked key and revokes the old credential immediately. Redeploy at once to inject the replacement; the current pod can&#39;t authenticate to Cursor in between.</p><h2 id="mcp-oauth" tabindex="-1">mcp oauth <a class="header-anchor" href="#mcp-oauth" aria-label="Permalink to &quot;mcp oauth&quot;">​</a></h2><p><code>mcp oauth</code> authorizes a <code>defineConnection({ url, oauth: true })</code> connection with a browser PKCE flow. Tokens are written to <code>mcp-auth.json</code> under the agent-serve config dir (default <code>~/.config/agent-serve</code>). Pass <code>--store</code> to upsert matching <code>MCP_OAUTH_&lt;CONNECTION&gt;_*</code> secrets on the hosted deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">connectio</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--store] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--team </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span></code></pre></div><p><code>&lt;connection&gt;</code> is the <code>agent/mcp-connections/&lt;connection&gt;.ts</code> basename. <code>--slug</code> defaults to the <code>--dir</code> basename. <code>--team</code> defaults to the signed-in account&#39;s team. You need <code>agentkit login</code> (or <code>--api-key</code>) before <code>--store</code>.</p><p>Secret names are <code>MCP_OAUTH_&lt;NAME&gt;_ACCESS_TOKEN</code>, <code>_REFRESH_TOKEN</code>, and <code>_CLIENT_ID</code> (<code>&lt;NAME&gt;</code> is the connection id in upper snake case). Declare them in <code>hosting.secretNames</code> so deploy validation expects them. Secrets apply on the next deploy.</p><p>Tokens are bound to the connection&#39;s resource URL. Changing the URL invalidates the local entry; run <code>mcp oauth</code> again.</p><p>See the <a href="./../guides/mcp-oauth.html">Host MCP OAuth guide</a>.</p><h2 id="secrets" tabindex="-1">secrets <a class="header-anchor" href="#secrets" aria-label="Permalink to &quot;secrets&quot;">​</a></h2><p><code>secrets</code> manages environment secrets for a deployment.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</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;"> NAME[=VALUE]...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</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:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secrets</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> unset</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;"> NAME</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--team </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:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--json]</span></span></code></pre></div><p>Omit <code>=VALUE</code> from <code>secrets set</code> to enter the value at a hidden TTY prompt. With piped stdin, provide one line for each missing value. Avoid values in command arguments because shells can record them in history.</p><p>Secret names use <code>UPPER_SNAKE_CASE</code>, start with a letter, and contain at most 64 characters. Names beginning with <code>CURSOR_</code> are reserved. Values can contain at most 4096 bytes, and one deployment can hold 32 secrets.</p><p><code>secrets list</code> returns names and creation times, never values. Secret changes reach the engine on its next deploy. <code>secrets set</code> upserts the named secrets without deleting others.</p><p>JSON output is <code>{ secretNames }</code> for <code>set</code>, <code>{ secrets }</code> for <code>list</code>, and <code>{ removed }</code> for <code>unset</code>.</p><h2 id="slack" tabindex="-1">slack <a class="header-anchor" href="#slack" aria-label="Permalink to &quot;slack&quot;">​</a></h2><p>The <code>slack</code> pack generates and checks Socket Mode channel setup.</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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--dir </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--name </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span></span>
@@ -58,4 +58,4 @@ import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--events a,b,c</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;*&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--action </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">action</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--comment </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--context </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--slug </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--channel </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--host </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">host</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--port </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--url </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--secret </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">secret</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</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><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,156)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    [--dry-run] [--out </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">dir</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] [--json]</span></span></code></pre></div><p><code>github events</code> prints each discovered channel&#39;s delivery URL and event set. When it finds no channels, it returns an empty result and exits successfully.</p><p><code>github forward</code> wraps <code>gh webhook forward</code>. It infers the repository from the Git remote when you omit <code>--repo</code> and <code>--org</code>. URLs and events come from the discovered channels; <code>--events</code> overrides the event set. Use <code>--slug</code> or <code>--channel</code> to narrow discovery when several channels match. Otherwise, one local proxy fans deliveries out to every match. <code>--url</code> targets one channel. For <code>forward</code>, pass <code>--events</code> when no matched channel can supply the event set.</p><p>Repository forwarding needs repo-admin access. Organization forwarding needs org-owner access. The relay authenticates with the GitHub CLI&#39;s stored login. A <code>GITHUB_TOKEN</code> or <code>GH_TOKEN</code> environment override can make delivery requests return <code>401</code>, even when hook creation succeeds. Unset those variables before forwarding.</p><p>Pass <code>--secret</code> or set <code>GITHUB_WEBHOOK_SECRET</code> to sign deliveries. <code>serve --dev</code> accepts unsigned loopback deliveries. A non-dev target requires the same secret on both sides.</p><p><code>github replay</code> needs read access, not admin access. It reads the pull request through <code>gh api</code>, builds GitHub webhook payloads, and posts them to the selected channels. Supported events are <code>pull_request</code>, <code>issue_comment</code>, <code>pull_request_review_comment</code>, <code>check_run</code>, <code>check_suite</code>, <code>workflow_run</code>, and <code>status</code>. The default is <code>pull_request</code> with action <code>synchronize</code>. Comment events need <code>--comment</code>.</p><p>Use <code>--events &#39;*&#39;</code> to replay every supported event declared by the channel. <code>--dry-run</code> prints payloads without posting them. <code>--out</code> writes fixture files but still posts unless you also pass <code>--dry-run</code>.</p><p><code>github doctor</code> checks <code>gh</code>, its login, and the pinned <code>cli/gh-webhook</code> extension. <code>--install</code> installs or repairs the extension. An environment-token override is a warning and doesn&#39;t make <code>github doctor</code> fail.</p><p>See the <a href="./../guides/github.html">GitHub guide</a>.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables&quot;">​</a></h2><p>These environment variables affect the CLI and its channel packs.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Meaning</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential. It takes precedence over the stored login.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend used by login, account, deployment, and event-relay RPCs in non-production environments.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend used by the Cursor SDK harness in non-production environments.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>Directory for stored credentials and update-check state. The default is <code>~/.config/agent-serve</code>.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code> / <code>NO_UPDATE_NOTIFIER</code></td><td>Disable the automatic published-version check when set to a non-empty value other than <code>0</code>.</td></tr><tr><td><code>CI</code></td><td>Disable the automatic published-version check when set.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default signing secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code> / <code>GITHUB_APP_PRIVATE_KEY</code> / <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App authentication for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code> / <code>GH_TOKEN</code></td><td>Token authentication for outbound API calls. Unset both for <code>github forward</code>.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code> / <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code> for each agent on a multi-agent host.</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><ul><li><a href="./project-layout.html">Project layout</a>: files the CLI discovers</li><li><a href="./http-api.html">HTTP API</a>: routes used by <code>chat</code>, <code>call</code>, and other clients</li><li><a href="./../deployment.html">Deployment</a>: production auth, state, and operations</li></ul>`,163)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_cli.md.CjfiV2Q-.lean.js → reference_cli.md.B74NrVzb.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",156)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};
+import{_ as i,c as e,o as a,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting.","frontmatter":{"title":"CLI","description":"Commands and common flags for local development, running servers, and Cursor-managed hosting."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function h(l,s,d,o,p,r){return a(),e("div",null,[...s[0]||(s[0]=[t("",163)])])}const g=i(n,[["render",h]]);export{c as __pageData,g as default};

package/dist/docs/assets/{reference_connections.md.FbWupyzW.js → reference_connections.md.CsSr3rDz.js}

@@ -1,9 +1,14 @@
-import{_ as i,c as e,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,c){return a(),e("div",null,[...s[0]||(s[0]=[n(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</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;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="mcp-connections" tabindex="-1">MCP Connections <a class="header-anchor" href="#mcp-connections" aria-label="Permalink to &quot;MCP Connections&quot;">​</a></h1><p>An MCP connection gives the agent tools from an MCP server. One file per server under <code>agent/mcp-connections/</code>, and the filename becomes the server name the model sees. An MCP connection default-exports <code>defineConnection</code> from <code>@cursor/july/connections</code>, and the transport comes in four shapes: remote HTTP, local stdio, the signed-in Cursor account&#39;s connectors, and peer agents on the same host.</p><h2 id="remote-mcp-server" tabindex="-1">Remote MCP server <a class="header-anchor" href="#remote-mcp-server" aria-label="Permalink to &quot;Remote MCP server&quot;">​</a></h2><p>Point an MCP connection at a remote server with a URL.</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;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/connections&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;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.linear.app/mcp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  headers: { authorization: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Bearer \${</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;">LINEAR_TOKEN</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><p>Tokens come from env vars. Never hardcode them in the file.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Tokens come from env vars. Never hardcode them in the file.</p><h2 id="host-mcp-oauth" tabindex="-1">Host MCP OAuth <a class="header-anchor" href="#host-mcp-oauth" aria-label="Permalink to &quot;Host MCP OAuth&quot;">​</a></h2><p>For servers that speak OAuth, set <code>oauth: true</code> and authorize with the CLI. Tokens live in <code>~/.config/agent-serve/mcp-auth.json</code>. <code>--store</code> copies them onto the hosted deployment as <code>MCP_OAUTH_&lt;NAME&gt;_*</code> secrets.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://mcp.example.com/inventory&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  oauth: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  hostOnly: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// model cannot call; host.mcp still can</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><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;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">           # browser PKCE → local mcp-auth.json</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agentkit</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> mcp</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> oauth</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inventory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --store</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">   # also upsert deployment secrets</span></span></code></pre></div><p>Full walkthrough: <a href="./../guides/mcp-oauth.html">Host MCP OAuth</a>. Companion skill: <a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>.</p><p>Use <code>hostOnly: true</code> when only deterministic host tools should call the server (deploys, admin APIs). Account MCP (<code>cursorAccount: true</code>) stays the right choice for connectors already linked in the Cursor dashboard.</p><h2 id="local-stdio-mcp-server" tabindex="-1">Local stdio MCP server <a class="header-anchor" href="#local-stdio-mcp-server" aria-label="Permalink to &quot;Local stdio MCP server&quot;">​</a></h2><p>Run a local MCP server as a child process with <code>command</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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  command: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;node&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  args: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;--import&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;tsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;mcp/units-server.ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // env, cwd</span></span>
@@ -23,4 +28,4 @@ import{_ as i,c as e,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const d
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">    const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</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;"> host.mcp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;linear&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;list_issues&quot;</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;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(result);</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></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</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="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,27)])])}const E=i(t,[["render",h]]);export{d as __pageData,E as default};
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div></li></ol><p>The host registry is small: <code>host.mcp.names()</code> lists MCP connection names, and <code>listTools(name)</code> / <code>callTool(name, tool, args)</code> open the client lazily on first use.</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="./../guides/mcp-oauth.html">Host MCP OAuth</a>: <code>mcp oauth</code>, <code>--store</code>, <code>hostOnly</code></li><li><a href="./../guides/agent-to-agent.html">Agent-to-agent</a>: peers in depth</li><li><a href="./tools.html">Tools</a>: authored tools that wrap MCP connections</li><li><a href="./../guides/webhooks.html">Webhooks</a>: calling MCP connections from handlers</li></ul>`,33)])])}const E=i(n,[["render",h]]);export{d as __pageData,E as default};

package/dist/docs/assets/{reference_connections.md.FbWupyzW.lean.js → reference_connections.md.CsSr3rDz.lean.js}

@@ -1 +1 @@
-import{_ as i,c as e,o as a,ag as n}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),t={name:"reference/connections.md"};function h(l,s,o,p,r,c){return a(),e("div",null,[...s[0]||(s[0]=[n("",27)])])}const E=i(t,[["render",h]]);export{d as __pageData,E as default};
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const d=JSON.parse(`{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents.","frontmatter":{"title":"MCP Connections","description":"Pull in tools from MCP servers: remote, stdio, the signed-in Cursor account's connectors, and peer agents."},"headers":[],"relativePath":"reference/connections.md","filePath":"reference/connections.md"}`),n={name:"reference/connections.md"};function h(l,s,o,p,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",33)])])}const E=i(n,[["render",h]]);export{d as __pageData,E as default};

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

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

@@ -0,0 +1 @@
+import{_ as e,c as i,o as t,ag as a}from"./chunks/framework.CAZyNGu9.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_tools.md.CqgJroI0.js → reference_tools.md.BRSDnTbN.js}

@@ -1,4 +1,4 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="tools" tabindex="-1">Tools <a class="header-anchor" href="#tools" aria-label="Permalink to &quot;Tools&quot;">​</a></h1><p>A tool is a typed action the model can call: hit an API, run a query, write a file. Each file in <code>agent/tools/</code> defines one tool, and the filename becomes the tool name the model sees. Tools come in two execution flavors: server tools run in-process on the serve host, and agent tools run as scripts where the agent runs. Every server tool can also be called directly, with no model turn.</p><h2 id="define-a-server-tool" tabindex="-1">Define a server tool <a class="header-anchor" href="#define-a-server-tool" aria-label="Permalink to &quot;Define a server tool&quot;">​</a></h2><p>By default, <code>execute</code> runs in-process on the serving host with full access to <code>process.env</code> and your <code>agent/lib/</code> code. Server tools require the <code>local</code> runtime.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/tools/inspect_pr.ts</span></span>
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="tools" tabindex="-1">Tools <a class="header-anchor" href="#tools" aria-label="Permalink to &quot;Tools&quot;">​</a></h1><p>A tool is a typed action the model can call: hit an API, run a query, write a file. Each file in <code>agent/tools/</code> defines one tool, and the filename becomes the tool name the model sees. Tools come in two execution flavors: server tools run in-process on the serve host, and agent tools run as scripts where the agent runs. Every server tool can also be called directly, with no model turn.</p><h2 id="define-a-server-tool" tabindex="-1">Define a server tool <a class="header-anchor" href="#define-a-server-tool" aria-label="Permalink to &quot;Define a server tool&quot;">​</a></h2><p>By default, <code>execute</code> runs in-process on the serving host with full access to <code>process.env</code> and your <code>agent/lib/</code> code. Server tools require the <code>local</code> runtime.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/tools/inspect_pr.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/tools&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { 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>
@@ -9,7 +9,20 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <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;">prUrl</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;">    return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { prUrl, checks: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;unit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;lint&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">], ready: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  },</span></span>
-<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>A tool definition needs a filename slug (the model-facing name), a <code>description</code> written for the model, an optional <code>inputSchema</code>, and the code that runs it. With a Zod <code>inputSchema</code>, the input is validated before <code>execute</code> runs and the input type is inferred. A plain JSON Schema object is forwarded as-is and the input arrives as raw JSON.</p><h3 id="the-ctx-parameter" tabindex="-1">The <code>ctx</code> parameter <a class="header-anchor" href="#the-ctx-parameter" aria-label="Permalink to &quot;The \`ctx\` parameter&quot;">​</a></h3><p><code>execute</code> receives a <code>ctx</code> with the runtime accessors:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.toolCallId</code></td><td>The call id, matching the <code>actions.requested</code> / <code>action.result</code> stream events</td></tr><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session&#39;s workspace directory</td></tr><tr><td><code>ctx.host.mcp</code></td><td>Authored MCP connections: <code>names()</code>, <code>listTools(name)</code>, <code>callTool(name, tool, args)</code></td></tr><tr><td><code>ctx.host.github</code> / <code>ctx.host.slack</code></td><td>Shared host clients when those packs are configured</td></tr></tbody></table><h3 id="return-values" tabindex="-1">Return values <a class="header-anchor" href="#return-values" aria-label="Permalink to &quot;Return values&quot;">​</a></h3><p><code>execute</code> may return a string (passed to the model verbatim), a JSON-shaped value (serialized), or the envelope <code>{ content: [...], isError? }</code> for rich results. Returns must be JSON-shaped: use object literals or <code>type</code> aliases. An <code>interface</code> type fails assignability (no index signature), and tsx won&#39;t catch it. Your typecheck will.</p><p>Throwing inside <code>execute</code> reports an error result to the model (<code>isError: true</code>). The turn and the server keep running.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. This is the only tool flavor available to <code>runtime: &quot;cloud&quot;</code> agents.</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:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>A tool definition needs a filename slug (the model-facing name), a <code>description</code> written for the model, an optional <code>inputSchema</code>, and the code that runs it. With a Zod <code>inputSchema</code>, the input is validated before <code>execute</code> runs and the input type is inferred. A plain JSON Schema object is forwarded as-is and the input arrives as raw JSON.</p><p>For multi-line descriptions, reminder prompts, and error messages, use <a href="./prompt.html"><code>prompt</code></a> so the string can sit indented with the surrounding TypeScript:</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>
+<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:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    Inspect a pull request before approval.</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">    Prefer this over guessing from the title alone.</span></span>
+<span class="line"><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;">  inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ prUrl: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">url</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;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prUrl</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;"> { prUrl };</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><h3 id="the-ctx-parameter" tabindex="-1">The <code>ctx</code> parameter <a class="header-anchor" href="#the-ctx-parameter" aria-label="Permalink to &quot;The \`ctx\` parameter&quot;">​</a></h3><p><code>execute</code> receives a <code>ctx</code> with the runtime accessors:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.toolCallId</code></td><td>The call id, matching the <code>actions.requested</code> / <code>action.result</code> stream events</td></tr><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session&#39;s workspace directory</td></tr><tr><td><code>ctx.host.mcp</code></td><td>Authored MCP connections: <code>names()</code>, <code>listTools(name)</code>, <code>callTool(name, tool, args)</code></td></tr><tr><td><code>ctx.host.github</code> / <code>ctx.host.slack</code></td><td>Shared host clients when those packs are configured</td></tr></tbody></table><h3 id="return-values" tabindex="-1">Return values <a class="header-anchor" href="#return-values" aria-label="Permalink to &quot;Return values&quot;">​</a></h3><p><code>execute</code> may return a string (passed to the model verbatim), a JSON-shaped value (serialized), or the envelope <code>{ content: [...], isError? }</code> for rich results. Returns must be JSON-shaped: use object literals or <code>type</code> aliases. An <code>interface</code> type fails assignability (no index signature), and tsx won&#39;t catch it. Your typecheck will.</p><p>Throwing inside <code>execute</code> reports an error result to the model (<code>isError: true</code>). The turn and the server keep running.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to &quot;Define an agent tool&quot;">​</a></h2><p>Set <code>execution: &quot;agent&quot;</code> and the tool materializes as a shell script that runs where the Cursor agent runs: the local harness workspace or the cloud VM. The script receives JSON arguments on stdin and prints its result on stdout. This is the only tool flavor available to <code>runtime: &quot;cloud&quot;</code> agents.</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>
@@ -43,4 +56,4 @@ import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c
 <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span></code></pre></div><p>Programmatically, <code>callTool(toolName, input, options?)</code> is available on the serve handle, on channel route handlers and <code>onStart</code> args, and on schedule <code>run</code> handlers, so a channel can mix deterministic calls with model turns, fetching PR metadata deterministically and then <code>send()</code>ing the review prompt:</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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> outcome</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;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;inspect_pr&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://github.com/acme/checkout/pull/42&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:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral scratch workspace under <code>&lt;stateRoot&gt;/tool-calls/&lt;callId&gt;</code>, materialized like a session workspace and removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream under a per-call <code>turnId</code>, visible in the playground and trajectories like any model-initiated call. Session-bound calls serialize with model turns and return <code>409 session_busy</code> while a turn runs.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>And gate side effects: <code>needsApproval</code> for the calls that need a person&#39;s sign-off, and dry-run defaults flipped by an env var for anything destructive.</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="./../guides/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,38)])])}const u=i(n,[["render",l]]);export{c as __pageData,u as default};
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>By default the call runs against an ephemeral scratch workspace under <code>&lt;stateRoot&gt;/tool-calls/&lt;callId&gt;</code>, materialized like a session workspace and removed when the call returns. Pass a <code>sessionId</code> (a body field over HTTP, <code>--session</code> on the CLI, <code>options.sessionId</code> programmatically) to run inside an existing session instead: the tool sees that session&#39;s workspace, and the call is recorded on the session&#39;s event stream under a per-call <code>turnId</code>, visible in the playground and trajectories like any model-initiated call. Session-bound calls serialize with model turns and return <code>409 session_busy</code> while a turn runs.</p><p>The error semantics match the model path. Unknown tools are rejected with the available names, agent-execution tools cannot be called on the host (<code>400</code>), schema-invalid input is a <code>400</code> before the tool body runs (Zod validates; plain JSON Schema passes through unvalidated), and a tool body that throws reports <code>isError: true</code> in the same envelope the model would see.</p><h2 id="design-habits" tabindex="-1">Design habits <a class="header-anchor" href="#design-habits" aria-label="Permalink to &quot;Design habits&quot;">​</a></h2><p>Keep one decision per tool. Small tools with crisp descriptions beat multi-purpose tools with mode flags. The model chooses better and evals gate cleaner.</p><p>Put deterministic policy in tool code, not model judgment. A PR-approval tool should re-read the live PR inside the tool before acting, so a spoofed payload can&#39;t steer it.</p><p>Test tools with <code>call</code> before blaming prompts. If the tool&#39;s output is wrong, no instruction change fixes it.</p><p>And gate side effects: <code>needsApproval</code> for the calls that need a person&#39;s sign-off, and dry-run defaults flipped by an env var for anything destructive.</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="./../guides/human-in-the-loop.html">Human-in-the-loop</a>: the approval lifecycle in full</li><li><a href="./connections.html">MCP connections</a>: tools that come from MCP servers instead</li><li><a href="./../evals.html">Evals</a>: gating tool decisions with <code>calledTool</code></li></ul>`,40)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};

package/dist/docs/assets/{reference_tools.md.CqgJroI0.lean.js → reference_tools.md.BRSDnTbN.lean.js}

@@ -1 +1 @@
-import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,p,r,d){return e(),a("div",null,[...s[0]||(s[0]=[t("",38)])])}const u=i(n,[["render",l]]);export{c as __pageData,u as default};
+import{_ as i,c as a,o as e,ag as t}from"./chunks/framework.CAZyNGu9.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, gate the sensitive ones on approval, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,p,o,r,k){return e(),a("div",null,[...s[0]||(s[0]=[t("",40)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};