@cursor/july 0.1.111 → 0.1.113

package/src/internal/server.ts

@@ -137,7 +137,10 @@ import {
   HOSTED_GUEST_RETRY_TERMINAL,
   hostedGuestErrorResponse,
 } from "./hosted-delivery-protocol.js";
-import { hostedErrorStackSnippet } from "./hosted-execution-diag.js";
+import {
+  hostedErrorMessageOnly,
+  hostedErrorStackSnippet,
+} from "./hosted-execution-diag.js";
 import { flushHostedExecutionProcessDeath } from "./hosted-execution-flush.js";
 import {
   buildHttpChannelRoutes,
@@ -238,6 +241,11 @@ import {
   unregisterSessionRunFatalFlush,
 } from "./session-run-log.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
+import {
+  readSkillDetail,
+  skillListEntry,
+  UnknownSkillError,
+} from "./skill-catalog.js";
 import { flushLocalStartLog, selectStartLogStore } from "./start-log-store.js";
 import { catalogDetailEntry, catalogListEntry } from "./tool-catalog.js";
 
@@ -1316,11 +1324,18 @@ export async function startServer(
           );
         }
       } else {
+        const resolveCloudToolsHeaders =
+          options.cloudToolsUrl === undefined
+            ? undefined
+            : (): Record<string, string> | undefined => {
+                const apiKey = liveCursorApiKey();
+                return apiKey === undefined
+                  ? undefined
+                  : { authorization: `Bearer ${apiKey}` };
+              };
         const headers =
           options.cloudToolsUrl !== undefined
-            ? accountKey === undefined
-              ? undefined
-              : { authorization: `Bearer ${accountKey.apiKey}` }
+            ? resolveCloudToolsHeaders?.()
             : options.authToken === undefined
               ? undefined
               : { authorization: `Bearer ${options.authToken}` };
@@ -1331,14 +1346,17 @@ export async function startServer(
             );
           }
           logger(
-            `[agent-sdk] --cloud-tools-url: listening unsigned; Bearer is taken from the key present at start`
+            `[agent-sdk] --cloud-tools-url: listening unsigned; Bearer resolves after task-time credential binding`
           );
         }
-        runtime.engine.setCloudServerToolsConnection({
-          type: "http",
-          url: publicToolsUrl,
-          ...(headers === undefined ? {} : { headers }),
-        });
+        runtime.engine.setCloudServerToolsConnection(
+          {
+            type: "http",
+            url: publicToolsUrl,
+            ...(headers === undefined ? {} : { headers }),
+          },
+          resolveCloudToolsHeaders
+        );
       }
     }
   }
@@ -1568,7 +1586,15 @@ function mountAgentRoutes(
     }
     return null;
   };
-  if (noControlPlane === true && isV2Project(project)) {
+  // A v2 mount served under `--no-control-plane` is a hosted v2 guest: the
+  // hosted control plane drives it through the hosted delivery route below.
+  // Session HTTP is a control-plane surface, so such a guest mounts no
+  // `/v1/session*` or `/v1/sessions` routes — session starts arrive as hosted
+  // admissions (`agentsdk.session` on the built-in http channel) and session
+  // reads come from the control plane's runs surface and durable storage.
+  // Local dev, self-hosted serve, and hosted v1 keep the engine mounts.
+  const hostedV2Guest = noControlPlane === true && isV2Project(project);
+  if (hostedV2Guest) {
     registerHostedDeliveryRoute({
       router,
       base,
@@ -1747,34 +1773,38 @@ function mountAgentRoutes(
     },
   });
 
-  router.add({
-    method: "GET",
-    pattern: `${base}/v1/sessions`,
-    auth: httpAuth,
-    handler: async (request, ctx) => {
-      // Same gate as requireSessionOwner / relaxSessionReadAuth: never with
-      // bearer or custom channel auth (strict per-principal isolation).
-      // `--allow-anonymous` alone is a shared-principal trust boundary (corp
-      // Okta ALB); `--dev` alone stays loopback-only.
-      const includeAll =
-        relaxSessionReadAuth &&
-        (relaxSessionReadAuthBeyondLoopback ||
-          (typeof ctx.requestIp === "string" &&
-            isLoopbackAddress(ctx.requestIp)));
-      // `?latest=1` — only the newest visible session. Clients binding a
-      // default session (agsh) do not need the whole list, and on hosted
-      // storage the whole list is a database scan.
-      const latest = new URL(request.url).searchParams.get("latest");
-      const listed =
-        latest === "1" || latest === "true"
-          ? await engine.latestSessionWithSource(ctx.auth, { includeAll })
-          : await engine.listSessionsWithSource(ctx.auth, { includeAll });
-      return jsonResponse({
-        sessions: listed.sessions,
-        source: listed.source,
-      });
-    },
-  });
+  // Session list is session surface: not mounted on a hosted v2 guest (the
+  // control plane owns session reads there; see hostedV2Guest above).
+  if (!hostedV2Guest) {
+    router.add({
+      method: "GET",
+      pattern: `${base}/v1/sessions`,
+      auth: httpAuth,
+      handler: async (request, ctx) => {
+        // Same gate as requireSessionOwner / relaxSessionReadAuth: never with
+        // bearer or custom channel auth (strict per-principal isolation).
+        // `--allow-anonymous` alone is a shared-principal trust boundary (corp
+        // Okta ALB); `--dev` alone stays loopback-only.
+        const includeAll =
+          relaxSessionReadAuth &&
+          (relaxSessionReadAuthBeyondLoopback ||
+            (typeof ctx.requestIp === "string" &&
+              isLoopbackAddress(ctx.requestIp)));
+        // `?latest=1` — only the newest visible session. Clients binding a
+        // default session (agsh) do not need the whole list, and on hosted
+        // storage the whole list is a database scan.
+        const latest = new URL(request.url).searchParams.get("latest");
+        const listed =
+          latest === "1" || latest === "true"
+            ? await engine.latestSessionWithSource(ctx.auth, { includeAll })
+            : await engine.listSessionsWithSource(ctx.auth, { includeAll });
+        return jsonResponse({
+          sessions: listed.sessions,
+          source: listed.source,
+        });
+      },
+    });
+  }
 
   // Durable artifacts (ctx.artifacts / tag_artifact), newest-updated first.
   router.add({
@@ -2084,6 +2114,45 @@ function mountAgentRoutes(
     },
   });
 
+  // Deterministic skill reads: the body the harness would receive, plus
+  // resolved sibling files. Read-only, so plain GETs with no session binding.
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/skills`,
+    auth: httpAuth,
+    handler: async () =>
+      jsonResponse({
+        skills: project.agent.skills.map(skillListEntry),
+      }),
+  });
+
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/skills/:skillName`,
+    auth: httpAuth,
+    handler: async (_request, ctx) => {
+      const skillName = ctx.params.skillName ?? "";
+      try {
+        return jsonResponse(
+          await readSkillDetail(project.agent.skills, skillName)
+        );
+      } catch (error) {
+        if (error instanceof UnknownSkillError) {
+          return jsonResponse(
+            {
+              ok: false,
+              error: "unknown_skill",
+              message: error.message,
+              availableSkills: error.availableSkillNames,
+            },
+            { status: 404 }
+          );
+        }
+        throw error;
+      }
+    },
+  });
+
   if (playground) {
     // Serve the built Vite SPA. `<base href>` is injected so the SPA's relative
     // asset URLs resolve under this mount regardless of the trailing slash the
@@ -2107,18 +2176,25 @@ function mountAgentRoutes(
     });
   }
 
-  for (const route of buildHttpChannelRoutes({
-    engine,
-    config: project.httpChannel,
-    auth: httpAuth,
-    basePath: base,
-    // Dev playground lists every session (`includeAll`); allow opening them
-    // (see relaxSessionReadAuth above).
-    relaxSessionReadAuth,
-    relaxSessionReadAuthBeyondLoopback,
-    relaxSessionApprovalAuth,
-  })) {
-    router.add(route);
+  // The built-in HTTP session channel (`/v1/session*`, including the
+  // session-scoped approvals/auths routes) is session surface: not mounted on
+  // a hosted v2 guest (see hostedV2Guest above). The `http` channel itself
+  // stays registered with the hosted delivery route, which is how the control
+  // plane's session starts reach it.
+  if (!hostedV2Guest) {
+    for (const route of buildHttpChannelRoutes({
+      engine,
+      config: project.httpChannel,
+      auth: httpAuth,
+      basePath: base,
+      // Dev playground lists every session (`includeAll`); allow opening them
+      // (see relaxSessionReadAuth above).
+      relaxSessionReadAuth,
+      relaxSessionReadAuthBeyondLoopback,
+      relaxSessionApprovalAuth,
+    })) {
+      router.add(route);
+    }
   }
 
   // Playground eval list/run — available without `--dev` (corp / allow-anonymous).
@@ -3087,8 +3163,9 @@ async function handleRequest(
         }`
       );
       const snippet = hostedErrorStackSnippet(error);
-      const message =
-        snippet.length > 0
+      const message = hostedDeliveryRequest
+        ? hostedErrorMessageOnly(error)
+        : snippet.length > 0
           ? `Internal server error: ${snippet}`
           : "Internal server error.";
       response = hostedDeliveryRequest

package/src/internal/session-engine.ts

@@ -591,6 +591,10 @@ export class SessionEngine {
   private resolvedConnections: EngineResolvedConnection[] = [];
   /** Direct server-tool HTTP MCP transport exposed only to cloud turns. */
   private cloudServerToolsConnection: ConnectionTransport | undefined;
+  /** Re-resolved after hosted v2 task binding writes the Cursor credential. */
+  private cloudServerToolsHeaders:
+    | (() => Record<string, string> | undefined)
+    | undefined;
   private readonly getCloudUsage: (
     sdkAgentId: string
   ) => Promise<CloudAgentUsage | undefined>;
@@ -756,8 +760,30 @@ export class SessionEngine {
     );
   }
 
-  setCloudServerToolsConnection(connection: ConnectionTransport): void {
+  setCloudServerToolsConnection(
+    connection: ConnectionTransport,
+    resolveHeaders?: () => Record<string, string> | undefined
+  ): void {
     this.cloudServerToolsConnection = connection;
+    this.cloudServerToolsHeaders = resolveHeaders;
+  }
+
+  private currentCloudServerToolsConnection(): ConnectionTransport | undefined {
+    const connection = this.cloudServerToolsConnection;
+    const resolveHeaders = this.cloudServerToolsHeaders;
+    if (
+      connection === undefined ||
+      !("url" in connection) ||
+      resolveHeaders === undefined
+    ) {
+      return connection;
+    }
+    const { headers: _headers, ...withoutHeaders } = connection;
+    const headers = resolveHeaders();
+    return {
+      ...withoutHeaders,
+      ...(headers === undefined ? {} : { headers }),
+    };
   }
 
   setMcpOauthCallbackUrl(url: string): void {
@@ -1037,6 +1063,11 @@ export class SessionEngine {
       // on a sessionless pod.
       throw new HostedAdmissionLocalSendError();
     }
+    if (options.clearCloudOverride === true && options.cloud !== undefined) {
+      throw new Error(
+        "send options cloud and clearCloudOverride cannot be combined"
+      );
+    }
     const identity =
       channelId === HTTP_CHANNEL_ID
         ? httpContinuationIdentity(this.project.httpChannel)
@@ -1127,11 +1158,18 @@ export class SessionEngine {
             ),
           }));
         }
-        // Refresh the cloud attach the same way: a follow-up send carries the
-        // caller's CURRENT cloud options (e.g. a PR attach re-derived per wake),
-        // and the first send's snapshot must not pin this session's turns to a
-        // stale repo/prUrl for the session's lifetime.
+        // A caller can explicitly return a continuation to the agent's
+        // configured runtime. Omission remains sticky for compatibility:
+        // follow-ups that do not know the original attach keep it.
         if (
+          sendOptions.clearCloudOverride === true &&
+          record.cloudOverride !== undefined
+        ) {
+          record = await this.updateRecord(record.sessionId, current => ({
+            ...current,
+            cloudOverride: undefined,
+          }));
+        } else if (
           sendOptions.cloud !== undefined &&
           JSON.stringify(sendOptions.cloud) !==
             JSON.stringify(record.cloudOverride)
@@ -3184,7 +3222,7 @@ export class SessionEngine {
     sessionId: string,
     connectionName: string
   ): ConnectionTransport | undefined {
-    const connection = this.cloudServerToolsConnection;
+    const connection = this.currentCloudServerToolsConnection();
     if (connection === undefined || !("url" in connection)) {
       return undefined;
     }
@@ -3338,8 +3376,8 @@ export class SessionEngine {
           `MCP connection name "${SERVER_TOOLS_MCP_SERVER_NAME}" is reserved for authored server tools on cloud turns.`
         );
       }
-      const connection = this.cloudServerToolsConnection;
-      if ("url" in connection) {
+      const connection = this.currentCloudServerToolsConnection();
+      if (connection !== undefined && "url" in connection) {
         const url = new URL(connection.url);
         url.searchParams.set("agentkitSessionId", sessionId);
         servers[SERVER_TOOLS_MCP_SERVER_NAME] = {

package/src/internal/skill-catalog.ts

@@ -0,0 +1,69 @@
+/**
+ * Deterministic skill reads (`GET /v1/skills`, `GET /v1/skills/:name`,
+ * `agent-sdk skill <name>`): the skill body exactly as the harness would
+ * receive it, plus resolved sibling files. No model turn, no session.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { DiscoveredSkill } from "../types.js";
+import { buildSkillMd } from "./workspace.js";
+
+export class UnknownSkillError extends Error {
+  constructor(
+    skillName: string,
+    readonly availableSkillNames: string[]
+  ) {
+    super(`Unknown skill "${skillName}"`);
+    this.name = "UnknownSkillError";
+  }
+}
+
+/** Light listing entry: routing hint only, like `info` shows. */
+export interface SkillListEntry {
+  name: string;
+  description: string;
+}
+
+/** Full read behind `GET /v1/skills/:name`. */
+export interface SkillDetailEntry extends SkillListEntry {
+  /** SKILL.md body without generated frontmatter. */
+  markdown: string;
+  /** Rendered SKILL.md the harness reads (frontmatter + body). */
+  skillMd: string;
+  /** Sibling files by package-relative path, with contents resolved. */
+  files: Record<string, string>;
+  extension?: string;
+}
+
+export function skillListEntry(skill: DiscoveredSkill): SkillListEntry {
+  return { name: skill.name, description: skill.description };
+}
+
+export async function readSkillDetail(
+  skills: readonly DiscoveredSkill[],
+  skillName: string
+): Promise<SkillDetailEntry> {
+  const skill = skills.find(s => s.name === skillName);
+  if (skill === undefined) {
+    throw new UnknownSkillError(
+      skillName,
+      skills.map(s => s.name)
+    );
+  }
+  // Null-prototype: authored keys (`defineSkill`) pass through
+  // unvalidated, and `__proto__` would silently vanish on a plain object.
+  const files: Record<string, string> = Object.create(null);
+  for (const [rel, source] of Object.entries(skill.files)) {
+    files[rel] =
+      "contents" in source
+        ? source.contents
+        : await readFile(source.sourcePath, "utf8");
+  }
+  return {
+    ...skillListEntry(skill),
+    markdown: skill.markdown,
+    skillMd: buildSkillMd(skill),
+    files,
+    extension: skill.extension,
+  };
+}

package/src/types.ts

@@ -1147,6 +1147,16 @@ export interface ExtensionOptions<TConfig, TInput = TConfig> {
   description?: string;
   /** Mount configuration schema. A consumer's settings are validated at mount. */
   config?: z.ZodType<TConfig, z.ZodTypeDef, TInput>;
+  /** Choose which contribution groups this mount includes. */
+  contributions?: (config: TConfig) => ExtensionContributionSelection;
+}
+
+/** Contribution groups a configured extension mount may include or omit. */
+export interface ExtensionContributionSelection {
+  /** Include tools from the extension tree. Defaults to true. */
+  tools?: boolean;
+  /** Include skills from the extension tree. Defaults to true. */
+  skills?: boolean;
 }
 
 /**
@@ -1181,6 +1191,7 @@ export interface CursorPluginDeclaration extends ExtensionDeclaration {
 export interface ExtensionMount extends BrandedDefinition<"extension"> {
   readonly extension: ExtensionDeclaration | CursorPluginDeclaration;
   readonly config: unknown;
+  readonly contributions?: ExtensionContributionSelection;
 }
 
 /** `cursorPlugin({ ... })`: mount a Cursor plugin directory as an extension. */
@@ -1479,13 +1490,20 @@ export type ConnectionConfig = (
    * Fail-closed: a `listTools` failure, an invalid tool name, or a name
    * collision (with an authored tool or another advertised connection)
    * fails the turn — a turn never silently runs with a shrunken toolset.
-   * Local runtime only, like all server tools: a `runtime: "cloud"` agent
-   * fails discovery, and hybrid per-send cloud sessions refuse the turn.
-   * The listing runs once per turn; point this at endpoints that can
+   * Set {@link optional} to skip this connection instead of failing the
+   * turn. Local runtime only, like all server tools: a `runtime: "cloud"`
+   * agent fails discovery, and hybrid per-send cloud sessions refuse the
+   * turn. The listing runs once per turn; point this at endpoints that can
    * answer `tools/list` cheaply. Tools whose MCP `annotations.title` is
    * `do-not-call` are omitted (vendor host-UI / MCP Apps helpers).
    */
   advertiseTools?: boolean;
+  /**
+   * With {@link advertiseTools}, a `listTools` or `auth` failure skips this
+   * connection (zero tools from it) instead of failing the turn. Other
+   * advertised connections still fail closed. Requires `advertiseTools`.
+   */
+  optional?: boolean;
   /**
    * Intended effects of tools this connection serves. When set, only
    * tools whose classified effect is in this set are advertised — a
@@ -2130,6 +2148,15 @@ export interface SendMessageOptions {
    * runtime is forced local with no override path.
    */
   cloud?: AgentCloudOptions;
+  /**
+   * Clear cloud options retained by an existing continuation session before
+   * starting this turn. Use when a caller intentionally moves a previously
+   * cloud-attached session back to the agent's configured runtime. Cannot be
+   * combined with {@link cloud}.
+   *
+   * On a new session this is a no-op.
+   */
+  clearCloudOverride?: boolean;
   /**
    * Seed the Cursor SDK agent id for a **new** session (ignored when the
    * continuation token matches an existing session). For cloud agents this
@@ -3237,6 +3264,8 @@ export interface DiscoveredConnection {
   auth?: ConnectionAuthProvider;
   /** Advertise-by-name from {@link ConnectionConfig.advertiseTools}. */
   advertiseTools?: boolean;
+  /** Skip a listing failure instead of failing the turn. */
+  optional?: boolean;
   /**
    * Normalized intended effects from {@link ConnectionConfig.effects}.
    * Absent means every listed tool is advertised.
@@ -3415,6 +3444,7 @@ export interface AgentProjectInfo {
     name: string;
     transport: string;
     advertiseTools?: boolean;
+    optional?: boolean;
     effects?: readonly ToolEffect[];
     tools?: readonly string[];
     disallowedTools?: readonly string[];

package/templates/thermo-quality-review/README.md

@@ -0,0 +1,35 @@
+# Thermo quality review
+
+Reviews pull requests for structural code quality. Posts one review comment.
+
+```bash
+npx @cursor/july init ./thermo-quality-review --template thermo-quality-review
+```
+
+## Run hosted
+
+```bash
+cd thermo-quality-review
+agent-sdk login
+agent-sdk deploy --cursor-events-repo acme/api
+```
+
+The deployment watches that repo through your team's Cursor GitHub
+connection. Open a PR to get a review.
+
+## Run locally
+
+```bash
+agent-sdk dev --cursor-events --repo acme/api
+```
+
+Or replay a PR without pushing:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+## Files
+
+- `agent/instructions.md`: what counts as a finding
+- `evals/review.eval.ts`: two smoke cases

package/templates/thermo-quality-review/agent/agent.ts

@@ -0,0 +1,8 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  tools: ["read"],
+  local: {
+    sandbox: true,
+  },
+});

package/templates/thermo-quality-review/agent/channels/github.ts

@@ -0,0 +1,42 @@
+import {
+  defaultGitHubPullRequestDispatch,
+  githubChannel,
+} from "@cursor/july/channels/github";
+
+const MAX_DIFF_CHARS = 150_000;
+
+export default githubChannel({
+  cursorAccount: true,
+  deliverReplies: false,
+  onComment: () => null,
+  onPullRequest: (ctx, pr) => {
+    if (pr.draft) {
+      return null;
+    }
+    const dispatch = defaultGitHubPullRequestDispatch(ctx, pr);
+    if (dispatch === null) {
+      return null;
+    }
+    return {
+      auth: dispatch.auth,
+      context: ["Read pr/diff.patch."],
+      async workspaceFiles() {
+        const octokit = await ctx.github.getOctokit();
+        const diff = await octokit.rest.pulls.get({
+          owner: ctx.repository.owner,
+          repo: ctx.repository.name,
+          pull_number: pr.number,
+          mediaType: { format: "diff" },
+        });
+        const text = String(diff.data);
+        return {
+          "pr/diff.patch":
+            text.length > MAX_DIFF_CHARS
+              ? `${text.slice(0, MAX_DIFF_CHARS)}\n…[truncated]\n`
+              : text,
+          "pr/head.sha": pr.headSha,
+        };
+      },
+    };
+  },
+});

package/templates/thermo-quality-review/agent/instructions.md

@@ -0,0 +1,43 @@
+# Thermo quality review
+
+You review pull requests for structural code quality. Be ambitious:
+look for restructures that delete whole branches, helpers, or layers,
+not tidier versions of the same idea.
+
+## Hunt
+
+- Missed code-judo moves: reframings that make complexity disappear.
+- Spaghetti growth: new conditionals or special cases bolted onto
+  unrelated flows. Push them behind their own abstraction.
+- Files the PR pushes past 1,000 lines. Ask for decomposition first.
+- Feature logic leaking into shared paths. Isolate it.
+- Wrappers, casts, `any`, and optionality that hide the real contract.
+- Bespoke helpers where a canonical one exists. Reuse it.
+- Gratuitous sequential orchestration and half-applied updates.
+
+## Skip
+
+- Style nits and behavior disputes.
+- Renames when the real issue is structural.
+
+## Bar
+
+Approve only with no structural regression, no unjustified size
+explosion, and no obvious missed simplification. Otherwise push for
+the cleaner decomposition.
+
+## Review
+
+The workspace has `pr/diff.patch`. Read it once. Call `post_findings`
+once with structured findings. Reply with the count and one line per
+finding. Clean review: empty findings.
+
+The host writes the GitHub comment. Verdict is CLEAN when the list
+is empty.
+
+## Finding
+
+- `severity`: `high`, `medium`, or `low`
+- `file`, `line`: path and line in the diff
+- `title`: short name
+- `detail`: one-line impact and fix