@cursor/july 0.1.91 → 0.1.93

package/src/internal/server.ts

@@ -56,6 +56,7 @@ import type {
   ReminderInfo,
   ServeOptions,
 } from "../types.js";
+import { V2EngineError } from "./continuation-identity.js";
 import {
   type CursorAccountConnectionRef,
   CursorAccountMcpBridge,
@@ -118,6 +119,7 @@ import {
   handleAgentServeTrigger,
 } from "./handleAgentServeTrigger.js";
 import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
+import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
 import {
   buildHttpChannelRoutes,
   errorResponse,
@@ -279,7 +281,11 @@ export async function startServer(
   );
   const dev = options.dev ?? false;
   const playground = options.playground ?? true;
-  const noControlPlane = options.noControlPlane === true;
+  const hosted = options as {
+    noControlPlane?: boolean;
+    cursorGithubProxy?: boolean;
+  };
+  const noControlPlane = hosted.noControlPlane === true;
   const runSchedules = options.schedules ?? !dev;
   const runReminders = options.reminders ?? !dev;
 
@@ -371,7 +377,7 @@ export async function startServer(
   // through github-proxy exactly like channel Octokit calls.
   let hostGithubProxyResolver: CursorAccountGithubTokenResolver | undefined;
   if (cursorGithubTargets.length > 0) {
-    const githubProxyRequested = options.cursorGithubProxy === true;
+    const githubProxyRequested = hosted.cursorGithubProxy === true;
     const needsGithubAuth =
       cursorGithubConfig.scope !== undefined || githubProxyRequested;
     if (needsGithubAuth) {
@@ -1285,6 +1291,19 @@ function mountAgentRoutes(
     }
     return null;
   };
+  if (noControlPlane === true && isV2Project(project)) {
+    registerHostedDeliveryRoute({
+      router,
+      base,
+      channels: project.channels,
+      buildHandlerArgs: (channelId, hostedSessionId) =>
+        buildChannelHandlerArgs({
+          runtime,
+          channelId,
+          hostedSessionId,
+        }),
+    });
+  }
   // Playground lists/opens Slack (and other channel) sessions across
   // principals when `--dev` (loopback) or `--allow-anonymous` (trusted
   // shared host, e.g. corp Okta ALB). Never when bearer / custom channel
@@ -2762,6 +2781,7 @@ function buildChannelHandlerArgs(input: {
   params?: Record<string, string>;
   requestIp?: string | null;
   auth?: AuthContext | null;
+  hostedSessionId?: string;
 }): ChannelHandlerArgs {
   const { runtime, channelId } = input;
   const base = runtime.slug === "" ? "" : `/${runtime.slug}`;
@@ -2776,6 +2796,7 @@ function buildChannelHandlerArgs(input: {
       runtime.engine.send(channelId, message, {
         ...sendOptions,
         auth: sendOptions.auth !== undefined ? sendOptions.auth : auth,
+        hostedSessionId: input.hostedSessionId,
       }),
     getSession: (sessionId) =>
       runtime.engine.getChannelSession(channelId, sessionId),
@@ -2838,6 +2859,12 @@ async function handleRequest(
   } catch (error) {
     if (error instanceof SessionBusyError) {
       response = errorResponse(409, "session_busy", error.message);
+    } else if (error instanceof V2EngineError) {
+      response = errorResponse(
+        409,
+        "v2_identity_conflict",
+        "Control-plane session identity conflicts with existing state."
+      );
     } else if (error instanceof SessionAuthError) {
       response = errorResponse(403, "forbidden", error.message);
     } else {

package/src/internal/session-engine.ts

@@ -283,6 +283,11 @@ interface ActiveToolContext {
 
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
+  /**
+   * Hosted v2 control-plane identity. Private host plumbing only: channel
+   * authors cannot choose a session id through the public SendMessageOptions.
+   */
+  hostedSessionId?: string;
 }
 
 interface CoalescedQueuedTurn {
@@ -816,6 +821,14 @@ export class SessionEngine {
     }
 
     if (existing !== undefined) {
+      if (
+        sendOptions.hostedSessionId !== undefined &&
+        existing.sessionId !== sendOptions.hostedSessionId
+      ) {
+        throw new V2EngineError(
+          `v2: continuation belongs to session ${existing.sessionId}, not ${sendOptions.hostedSessionId}`
+        );
+      }
       if (!samePrincipal(existing.auth, auth)) {
         throw new SessionAuthError(existing.sessionId);
       }
@@ -886,11 +899,22 @@ export class SessionEngine {
       );
     }
 
+    if (sendOptions.hostedSessionId !== undefined) {
+      const collision = await this.getOrRestoreSession(
+        sendOptions.hostedSessionId
+      );
+      if (collision !== undefined) {
+        throw new V2EngineError(
+          `v2: hosted session id ${sendOptions.hostedSessionId} already belongs to another mailbox`
+        );
+      }
+    }
+
     const now = new Date().toISOString();
     const channelState = this.initialChannelState(channelId, sendOptions.state);
     const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
     let record: SessionRecord = {
-      sessionId: newSessionId(),
+      sessionId: sendOptions.hostedSessionId ?? newSessionId(),
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
@@ -2384,14 +2408,12 @@ export class SessionEngine {
       tools[tool.name] = {
         description: tool.description,
         inputSchema: tool.inputSchema as SDKCustomTool["inputSchema"],
-        // `SDKCustomTool.outputSchema` ships in the next published
-        // @cursor/sdk; the conditional spread carries the field through the
-        // pinned SDK's type until the dependency bumps, at which point local
-        // runs start advertising it.
         ...(tool.outputSchema === undefined
           ? {}
-          : { outputSchema: tool.outputSchema }),
-        // Same pinned-SDK carry for `SDKCustomTool.annotations`: an advertised
+          : {
+              outputSchema: tool.outputSchema as SDKCustomTool["outputSchema"],
+            }),
+        // Pinned-SDK carry for `SDKCustomTool.annotations`: an advertised
         // MCP passthrough's server-declared hints (bounded at listing time)
         // ride into the harness listing once the dependency bumps.
         ...(tool.annotations === undefined

package/src/internal/shallow-clone.ts

@@ -155,8 +155,14 @@ export type CommitRangeDiff =
 export async function tryDiffCommitRange(args: {
   /** Existing checkout to run git in (see {@link createShallowPrCheckout}). */
   checkoutDir: string;
-  /** The checkout's clone target; supplies the remote's ref + auth conventions. */
-  target: ScmCloneTarget;
+  /**
+   * The checkout's clone target; supplies the remote's ref + auth
+   * conventions. Omit for SCMs without a clone target (e.g. Origin, where
+   * the host checkout is the reviewed repo): the diff then relies on
+   * commits already present locally, plus one uncredentialed fetch-by-SHA
+   * through the checkout's own remote.
+   */
+  target?: ScmCloneTarget | undefined;
   from: string;
   to: string;
   /** Restrict the diff to one path when set. */
@@ -171,10 +177,13 @@ export async function tryDiffCommitRange(args: {
         "Could not compute a reliable diff because a commit SHA was not a full 40-character SHA.",
     };
   }
-  const credential = cloneCredential(
-    args.target,
-    args.auth ?? defaultCloneAuth(args.target)
-  );
+  const credential =
+    args.target === undefined
+      ? undefined
+      : cloneCredential(
+          args.target,
+          args.auth ?? defaultCloneAuth(args.target)
+        );
   for (const sha of [args.from, args.to]) {
     if (
       !(await ensureCommitFetched(
@@ -222,7 +231,7 @@ function isFullCommitSha(value: string): boolean {
 async function ensureCommitFetched(
   checkoutDir: string,
   sha: string,
-  target: ScmCloneTarget,
+  target: ScmCloneTarget | undefined,
   credential: GitCredential | undefined
 ): Promise<boolean> {
   if ((await revParse(checkoutDir, sha)) !== undefined) {
@@ -231,15 +240,20 @@ async function ensureCommitFetched(
   const attempts = [
     [...FETCH_ARGS, sha],
     // Deeper history on the PR head ref: the older end of an inter-run range
-    // is usually an ancestor of the tip rather than the tip itself.
-    [
-      "fetch",
-      "--depth=200",
-      "--no-tags",
-      "--quiet",
-      "origin",
-      target.prHeadRef,
-    ],
+    // is usually an ancestor of the tip rather than the tip itself. Only
+    // possible when the clone target (and so the PR head ref) is known.
+    ...(target === undefined
+      ? []
+      : [
+          [
+            "fetch",
+            "--depth=200",
+            "--no-tags",
+            "--quiet",
+            "origin",
+            target.prHeadRef,
+          ],
+        ]),
   ];
   for (const attempt of attempts) {
     try {

package/src/types.ts

@@ -263,7 +263,8 @@ export interface AgentConfig {
    * deploys onto the v2 control plane (v2 APIs and schemas). Omitted
    * channel `continuation` then inherits from declared events (`github.pr/v2`,
    * `github.issue/v2`, `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
-   * `none/v2`). An explicit per-channel selector still overrides.
+   * `deployments.deployment/v2`, `none/v2`). An explicit per-channel selector
+   * still overrides.
    *
    * ```ts
    * export default defineAgent({
@@ -2160,6 +2161,11 @@ export interface ChannelMeta {
    * to dispatch on. Used by `--cursor-events` to subscribe `provider: "origin"`.
    */
   originWebhookEvents?: readonly string[];
+  /**
+   * For deployments packs: the factory event types this channel is wired
+   * to dispatch on. Extracted into the deploy manifest as `eventTypes`.
+   */
+  deploymentEventTypes?: readonly string[];
   /**
    * For Slack packs with the opt-in channel watch: the allowlisted channels
    * (ids or `#names`) this channel dispatches on without a mention. Surfaced
@@ -2840,6 +2846,8 @@ export interface AgentProjectInfo {
     githubWebhookEvents?: readonly string[];
     /** Origin webhook event types the channel dispatches on, when declared. */
     originWebhookEvents?: readonly string[];
+    /** Factory deployment event types the channel dispatches on, when declared. */
+    deploymentEventTypes?: readonly string[];
     /** Slack channels watched for posts (opt-in channel watch), when declared. */
     slackChannelPosts?: readonly string[];
   }>;
@@ -2997,12 +3005,6 @@ export interface ServeOptions {
    * or `handle.dispatchReminder`.
    */
   reminders?: boolean;
-  /**
-   * Do not start the bundled control plane (schedule/reminder clocks).
-   * Cursor hosting passes this so the kit talks to the Cursor backend
-   * instead. Local `serve` should leave this unset.
-   */
-  noControlPlane?: boolean;
   /**
    * Serve the bundled web playground at `/playground` (chat, streaming,
    * tool calls, sessions, schedule dispatch). Defaults to true; the API
@@ -3047,16 +3049,6 @@ export interface ServeOptions {
    * authenticates callers (e.g. an SSO/Okta proxy in front of the host).
    */
   allowAnonymousGrokbot?: boolean;
-  /**
-   * Route `githubChannel({ cursorAccount })` API calls through the Cursor
-   * backend's GitHub forwarder (`/v0/github-proxy`) instead of minting raw
-   * installation tokens into this process. The backend logs and meters every
-   * call with per-deployment attribution. `AGENT_SERVE_GITHUB_PROXY_URL`
-   * overrides the forwarder base URL (default: the resolved Cursor API base
-   * URL + `/v0/github-proxy`). Child `gh` processes still use a minted
-   * `GH_TOKEN` lease (proxying `gh` is a follow-up).
-   */
-  cursorGithubProxy?: boolean;
   /**
    * Allow {@link allowAnonymous} together with
    * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`

package/dist/docs/assets/building-with-agents.md.DH8A_cHA.js

@@ -1,13 +0,0 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="building-agents-with-agents" tabindex="-1">Building agents with agents <a class="header-anchor" href="#building-agents-with-agents" aria-label="Permalink to &quot;Building agents with agents&quot;">​</a></h1><p>Give a coding agent the goal. The built-in skills guide it through scaffolding, channels, verification, evals, and measured improvement.</p><h2 id="what-can-a-coding-agent-build-for-me" tabindex="-1">What can a coding agent build for me? <a class="header-anchor" href="#what-can-a-coding-agent-build-for-me" aria-label="Permalink to &quot;What can a coding agent build for me?&quot;">​</a></h2><p>A coding agent can take an Agent SDK project from an idea to a verified first version. It can:</p><ul><li>Create the project and choose the smallest useful surface</li><li>Add tools, skills, channels, MCP connections, and approval gates</li><li>Run a real turn and inspect its trace</li><li>Add evals for the behavior you want to keep</li><li>Improve the agent against fixed inputs</li></ul><p>This works because the project surface lives in files. The CLI also returns structured JSON and records each run as an NDJSON trace. Your coding agent can inspect what the framework discovered, run the agent, and verify the result without reading terminal prose.</p><h2 id="how-do-i-create-an-agent-with-the-built-in-skill" tabindex="-1">How do I create an agent with the built-in skill? <a class="header-anchor" href="#how-do-i-create-an-agent-with-the-built-in-skill" aria-label="Permalink to &quot;How do I create an agent with the built-in skill?&quot;">​</a></h2><p>Have the coding agent read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> (in the monorepo: <code>packages/agent-serve/skills/create-agent/SKILL.md</code>) and follow it.</p><p>The skill asks about your agent&#39;s purpose, runtime, model, channels, MCP connections, and capabilities. It then shows you a plan, writes the project, and verifies the result.</p><p>For example:</p><blockquote><p>Use the Agent SDK create-agent skill to build a PR triage agent reachable through GitHub. It should summarize failed checks, require approval before posting a review, and include one smoke eval.</p></blockquote><p>The skill starts with a small surface: short instructions, one or two tools, the channels you chose, and a smoke eval. You can add more after the first end-to-end turn works.</p><h2 id="which-built-in-skill-should-i-use" tabindex="-1">Which built-in skill should I use? <a class="header-anchor" href="#which-built-in-skill-should-i-use" aria-label="Permalink to &quot;Which built-in skill should I use?&quot;">​</a></h2><p>The package ships task-specific guides under <a href="./../skills/"><code>skills/</code></a>:</p><table tabindex="0"><thead><tr><th>What you want to do</th><th>Skill</th></tr></thead><tbody><tr><td>Understand the project layout and runtimes</td><td><a href="./../skills/framework-map/SKILL.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./../skills/create-agent/SKILL.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./../skills/evals/SKILL.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./../skills/ab/SKILL.html"><code>ab</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./../skills/github/SKILL.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./../skills/setup-slack/SKILL.html"><code>setup-slack</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./../skills/debug/SKILL.html"><code>debug</code></a></td></tr></tbody></table><p>Point your coding agent at the matching <code>SKILL.md</code>. The guide contains the workflow, commands, and common mistakes for that task.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The skill bodies use the current <code>agent-serve</code> CLI names. This guide uses the upcoming <code>agent-sdk</code> names. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="how-does-a-coding-agent-verify-its-work" tabindex="-1">How does a coding agent verify its work? <a class="header-anchor" href="#how-does-a-coding-agent-verify-its-work" aria-label="Permalink to &quot;How does a coding agent verify its work?&quot;">​</a></h2><p>The coding agent should discover the project, test each server tool, run a real turn, and finish with evals:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --input</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;{&quot;prUrl&quot;:&quot;https://github.com/acme/checkout/pull/42&quot;}&#39;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
-<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Is https://github.com/acme/checkout/pull/42 ready to approve?&quot;</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> trajectory</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .agent-serve/traces/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sessionI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.ndjson</span></span>
-<span class="line"></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --list</span></span>
-<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span></code></pre></div><p><code>serve</code> boots without an API key, which is enough to check channel mounts and the playground shell. Model turns need a credential. When the environment lacks one, finish every key-free check, then hand the <code>run</code> and <code>eval</code> commands to the operator.</p><p>Test server tools with <code>call</code> before tuning the prompt. It runs a tool in-process with schema validation and no model turn. If the tool returns the wrong data, a prompt change won&#39;t fix it.</p><p><code>validate</code> and <code>run</code> don&#39;t type-check the project because tsx strips types. Run the project&#39;s TypeScript check before shipping. Tool results must also be JSON-shaped. Use object literals or <code>type</code> aliases for <code>execute</code> return types instead of <code>interface</code> types.</p><h2 id="how-do-i-improve-the-agent-after-its-first-run" tabindex="-1">How do I improve the agent after its first run? <a class="header-anchor" href="#how-do-i-improve-the-agent-after-its-first-run" aria-label="Permalink to &quot;How do I improve the agent after its first run?&quot;">​</a></h2><p>Scaffolding proves the agent runs. It says nothing about quality. Once a smoke turn passes, give the hillclimb skill:</p><ol><li><strong>Fixtures</strong>: one to three fixed inputs, such as a PR URL, a canonical question, or a saved webhook payload</li><li><strong>Success criteria</strong>: correct tool choice, fewer tool calls, lower wall time, or better output</li><li><strong>The freeze line</strong>: the API contract, output shape, and existing evals that must stay unchanged</li></ol><p>Have the coding agent read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. It measures the current run, proposes one change, remeasures the same fixtures, and adds an eval for each kept improvement.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Create your first agent</a></li><li><a href="./scaffolding-agents.html">Scaffold an agent with Cursor</a></li><li><a href="./evals.html">Evals</a></li><li><a href="./hillclimbing.html">Hillclimbing</a></li><li><a href="./reference/cli.html">CLI reference</a></li></ul>`,29)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};