@cursor/july 0.1.94 → 0.1.95

package/src/internal/review-comments.ts

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import type { HostGitHubClient } from "../types.js";
+import { parsePrUrl } from "./scm/pr-url.js";
 
 export type ReviewCommentPublisher = "local_gh" | "host_github" | "host_origin";
 
@@ -198,8 +199,15 @@ export type ReviewThreadResolverImplementation = {
 export function resolveScmReviewTarget(
   prUrl: string
 ): ScmReviewTarget | undefined {
-  const parsed = parseReviewPrUrl(prUrl);
-  return parsed.kind === "valid" ? parsed.value : undefined;
+  const parsed = parsePrUrl(prUrl);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  return {
+    provider: parsed.provider,
+    repo: `${parsed.owner}/${parsed.repo}`,
+    prNumber: parsed.number,
+  };
 }
 
 /**
@@ -1243,117 +1251,6 @@ function skippedResolve(detail: string): ResolveReviewThreadsResult {
   };
 }
 
-const ORIGIN_PR_PAGE_HOST_PATTERN = /^origin(-[a-z0-9]+)?\.cursor\.com$/i;
-
-/**
- * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
- * `parsePrTarget` in security-review-lib accepts. Duplicated here so
- * agent-serve does not import that package.
- */
-function parseReviewPrUrl(
-  prUrl: string
-):
-  | { kind: "valid"; value: ScmReviewTarget }
-  | { kind: "invalid"; detail: string } {
-  let url: URL;
-  try {
-    url = new URL(prUrl);
-  } catch (error) {
-    return {
-      kind: "invalid",
-      detail: `unparseable PR URL: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-
-  const parts = url.pathname.split("/").filter(Boolean);
-  const hostname = url.hostname;
-
-  if (hostname === "github.com" && parts.length >= 4 && parts[2] === "pull") {
-    const prNumber = Number(parts[3]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "github",
-          repo: `${parts[0]}/${parts[1]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (
-    ORIGIN_PR_PAGE_HOST_PATTERN.test(hostname) &&
-    parts.length >= 4 &&
-    parts[2] === "github"
-  ) {
-    const prNumber = Number(parts[3]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "origin",
-          repo: `${parts[0]}/${parts[1]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (
-    /^(www\.)?cursor\.com$/i.test(hostname) &&
-    parts[0] === "codebase" &&
-    parts.length >= 5 &&
-    parts[3] === "pull"
-  ) {
-    const prNumber = Number(parts[4]);
-    if (Number.isInteger(prNumber) && prNumber > 0) {
-      return {
-        kind: "valid",
-        value: {
-          provider: "origin",
-          repo: `${parts[1]}/${parts[2]}`,
-          prNumber,
-        },
-      };
-    }
-  }
-
-  if (hostname === "review.cursor.com" && parts[0] === "pr") {
-    if (parts.length >= 5 && parts[3] === "github") {
-      const prNumber = Number(parts[4]);
-      if (Number.isInteger(prNumber) && prNumber > 0) {
-        return {
-          kind: "valid",
-          value: {
-            provider: "origin",
-            repo: `${parts[1]}/${parts[2]}`,
-            prNumber,
-          },
-        };
-      }
-    }
-    if (parts.length >= 4) {
-      const prNumber = Number(parts[3]);
-      if (Number.isInteger(prNumber) && prNumber > 0) {
-        return {
-          kind: "valid",
-          value: {
-            provider: "origin",
-            repo: `${parts[1]}/${parts[2]}`,
-            prNumber,
-          },
-        };
-      }
-    }
-  }
-
-  return {
-    kind: "invalid",
-    detail: "unparseable PR URL: not a GitHub or Origin pull request",
-  };
-}
-
 function parseGithubPrUrl(
   prUrl: string
 ):

package/src/internal/scm/pr-url.ts

@@ -0,0 +1,95 @@
+/**
+ * Provider-neutral PR URL parse. GitHub.com plus the Origin page shapes
+ * humans paste: cursor.com/codebase, review.cursor.com/pr, origin.cursor.com.
+ */
+
+export type PrProvider = "github" | "origin";
+
+export type ParsedPrUrl = {
+  provider: PrProvider;
+  owner: string;
+  repo: string;
+  number: number;
+  url: string;
+};
+
+const ORIGIN_PAGE = /^origin(-[a-z0-9]+)?\.cursor\.com$/i;
+
+function positiveInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    return undefined;
+  }
+  return n;
+}
+
+function parsed(
+  provider: PrProvider,
+  owner: string | undefined,
+  repo: string | undefined,
+  number: number | undefined
+): ParsedPrUrl | undefined {
+  if (owner === undefined || repo === undefined || number === undefined) {
+    return undefined;
+  }
+  const url =
+    provider === "origin"
+      ? `https://cursor.com/codebase/${owner}/${repo}/pull/${number}`
+      : `https://github.com/${owner}/${repo}/pull/${number}`;
+  return { provider, owner, repo, number, url };
+}
+
+/** Strip Slack mrkdwn wrappers and trailing punctuation before `URL`. */
+function normalizeRaw(raw: string): string {
+  return raw
+    .trim()
+    .replace(/^[<[]+/, "")
+    .replace(/[>\].,;]+$/, "");
+}
+
+export function parsePrUrl(raw: string): ParsedPrUrl | undefined {
+  let url: URL;
+  try {
+    url = new URL(normalizeRaw(raw));
+  } catch {
+    return undefined;
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+  const host = url.hostname.toLowerCase();
+
+  if (
+    (host === "github.com" || host === "www.github.com") &&
+    parts.length >= 4 &&
+    parts[2] === "pull"
+  ) {
+    return parsed("github", parts[0], parts[1], positiveInt(parts[3]));
+  }
+
+  if (ORIGIN_PAGE.test(host) && parts.length >= 4 && parts[2] === "github") {
+    return parsed("origin", parts[0], parts[1], positiveInt(parts[3]));
+  }
+
+  if (
+    (host === "cursor.com" || host === "www.cursor.com") &&
+    parts[0] === "codebase" &&
+    parts.length >= 5 &&
+    parts[3] === "pull"
+  ) {
+    return parsed("origin", parts[1], parts[2], positiveInt(parts[4]));
+  }
+
+  if (host === "review.cursor.com" && parts[0] === "pr") {
+    if (parts.length >= 5 && parts[3] === "github") {
+      return parsed("origin", parts[1], parts[2], positiveInt(parts[4]));
+    }
+    if (parts.length >= 4) {
+      return parsed("origin", parts[1], parts[2], positiveInt(parts[3]));
+    }
+  }
+
+  return undefined;
+}

package/src/internal/sdk-runner.ts

@@ -29,6 +29,7 @@ import {
   type TurnUsage,
 } from "../types.js";
 import { mapSdkTokenUsage, usageTokenSum } from "./cloud-turn-cost.js";
+import type { ConversationMirror } from "./conversation-mirror.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 
 /** Internal seam between the session engine and the Cursor SDK harness. */
@@ -117,6 +118,13 @@ export interface CursorSdkRunnerOptions {
    * `LocalAgentStore` for heavy multi-session concurrency.
    */
   store?: LocalAgentStore;
+  /**
+   * Durable mirror for local conversations (v2 hosted engines). Hydrated
+   * before `Agent.resume` so a follow-up landing on a fresh pod finds the
+   * conversation, and persisted — awaited — after each local turn settles,
+   * because a hosted pod can be parked right after the execution reply.
+   */
+  conversationMirror?: ConversationMirror;
   /** Diagnostics for degraded paths (resume-miss fallback). */
   logger?: (line: string) => void;
   /**
@@ -316,6 +324,13 @@ export class CursorSdkRunner implements AgentRunner {
       }
       try {
         const result = await run.wait();
+        // Mirror the conversation before replying: on hosted v2 the pod can
+        // be parked as soon as the execution reply lands, so a
+        // fire-and-forget write would race VM teardown. Failed turns still
+        // checkpoint the user message, so they persist too.
+        if (request.runtime === "local") {
+          await this.persistConversation(request, agent.agentId);
+        }
         let outcome = toTurnOutcome(result);
         if (outcome.status === "error") {
           // An error result usually means the handle's transport is poisoned
@@ -469,8 +484,7 @@ export class CursorSdkRunner implements AgentRunner {
   private async buildLocalOptions(
     request: RunnerPrewarmRequest
   ): Promise<AgentOptions> {
-    const store =
-      this.options.store ?? (await this.getStore(request.runnerStateDir));
+    const store = await this.resolveStore(request);
     return {
       ...this.buildSharedOptions(request),
       // The built-in tool allowlist rides AgentOptions, not `local`, and is
@@ -507,6 +521,15 @@ export class CursorSdkRunner implements AgentRunner {
     }
 
     const agentId = request.sdkAgentId ?? request.sessionId;
+    const mirror = this.options.conversationMirror;
+    if (mirror !== undefined) {
+      // Host replacement: restore the conversation from the durable mirror
+      // before resuming, so the thread continues instead of starting fresh.
+      // A sink failure propagates and fails the turn (retryable) — reading
+      // an outage as "nothing mirrored" would silently fork the thread.
+      const store = await this.resolveStore(request);
+      await mirror.hydrate(store, agentId);
+    }
     try {
       return await Agent.resume(agentId, options);
     } catch (error) {
@@ -570,6 +593,38 @@ export class CursorSdkRunner implements AgentRunner {
     return Agent.create(options);
   }
 
+  private resolveStore(
+    request: Pick<RunnerPrewarmRequest, "runnerStateDir">
+  ): Promise<LocalAgentStore> {
+    return this.options.store !== undefined
+      ? Promise.resolve(this.options.store)
+      : this.getStore(request.runnerStateDir);
+  }
+
+  /**
+   * Mirror the settled turn's conversation. Persist failures are logged and
+   * dropped — a durable-mirror outage must not fail a turn that already ran.
+   */
+  private async persistConversation(
+    request: RunnerTurnRequest,
+    sdkAgentId: string
+  ): Promise<void> {
+    const mirror = this.options.conversationMirror;
+    if (mirror === undefined) {
+      return;
+    }
+    try {
+      const store = await this.resolveStore(request);
+      await mirror.persist(store, sdkAgentId);
+    } catch (error) {
+      this.log(
+        `[agent-sdk] conversation mirror: persist for ${sdkAgentId} failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  }
+
   private getStore(stateDir: string): Promise<LocalAgentStore> {
     let storePromise = this.stores.get(stateDir);
     if (storePromise === undefined) {

package/src/internal/server.ts

@@ -51,6 +51,7 @@ import type {
   ServeOptions,
 } from "../types.js";
 import { V2EngineError } from "./continuation-identity.js";
+import { selectConversationMirror } from "./conversation-mirror.js";
 import {
   type CursorAccountConnectionRef,
   CursorAccountMcpBridge,
@@ -516,12 +517,21 @@ export async function startServer(
       "[agent-sdk] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts"
     );
   }
+  // v2 hosted engines mirror the SDK conversation store to the deployment's
+  // shared file storage so a fresh pod resumes threads instead of forking
+  // them. Hosted serve is single-agent; a multi-mount serve (dev) has no
+  // single agent name to mint keys under and does not mirror.
+  const conversationMirror =
+    mounts.length === 1 && mounts[0] !== undefined
+      ? selectConversationMirror({ project: mounts[0].project, logger })
+      : undefined;
   const sdkRunner =
     options.runner ??
     new CursorSdkRunner({
       ...(options.apiKey === undefined || options.apiKey.trim() === ""
         ? {}
         : { apiKey: options.apiKey }),
+      ...(conversationMirror === undefined ? {} : { conversationMirror }),
       logger,
     });
   // Grok Bot turns run on Cursor's hosted Grok Bot (Sand) harness through

package/src/internal/session-engine.ts

@@ -113,6 +113,10 @@ import {
   createHostSlackClient,
   type HostPlatforms,
 } from "./host-platforms.js";
+import {
+  HostedAdmissionLocalSendError,
+  isDuringHostedAdmission,
+} from "./hosted-admission-context.js";
 import {
   formatContinuationToken,
   newContinuationKey,
@@ -465,6 +469,7 @@ export class SessionEngine {
     // for why the choice does not belong to the agent author.
     const frameworkStorage = selectFrameworkStorageDefinition({
       authored: options.project.storage,
+      architecture: options.project.agent.architecture,
     });
     this.storage =
       frameworkStorage === undefined
@@ -811,6 +816,13 @@ export class SessionEngine {
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
+    if (isDuringHostedAdmission()) {
+      // Only sends that bypassed the admission capture stub (typically a
+      // startup-captured `onStart` send) reach the engine inside the
+      // admission window; running one would leak an invisible local session
+      // on a sessionless pod.
+      throw new HostedAdmissionLocalSendError();
+    }
     const identity =
       channelId === HTTP_CHANNEL_ID
         ? httpContinuationIdentity(this.project.httpChannel)

package/src/storage-backends/cursor-hosted.ts

@@ -74,8 +74,13 @@ export interface CursorHostedStorageOptions {
    * `https://api.cursor.com`).
    */
   baseUrl?: string;
-  /** Bearer credential (default: `CURSOR_API_KEY`). */
-  apiKey?: string;
+  /**
+   * Bearer credential (default: `CURSOR_API_KEY`). A function is
+   * re-resolved on every call: hosted freeze snapshots listen unsigned and
+   * bind the key file after serve start, so a value captured at construct
+   * time would be permanently absent.
+   */
+  apiKey?: string | (() => string | undefined);
   /** Injected for tests. */
   fetch?: typeof fetch;
 }
@@ -180,7 +185,9 @@ function toCasResult(response: KvCasResponse): KvCasResult {
 }
 
 function resolveApiKey(options: CursorHostedStorageOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  const configured =
+    typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(
       "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"

package/templates/agentic-owners/README.md

@@ -58,7 +58,7 @@ policy only) opts paths out entirely.
 - One model turn per PR head assesses the diff against the base rubric
   (`agent/lib/owners/prompts/base-review.md`) plus matched rule prompts.
 - The model records a verdict with `record_review`; the host recomputes
-  the policy and applies the deterministic decision — approve, or request
+  the policy and applies the deterministic decision: approve, or request
   the policy owners (max 2, never the author) and leave one comment it
   keeps updated.
 - The model never writes to GitHub. Broken policy files fail closed with

package/templates/agentic-owners/agent/agent.ts

@@ -1,18 +1,8 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  },
   tools: ["read", "grep", "glob", "ls"],
   local: {
     sandbox: true,
-    cwd: join(homedir(), ".cache", "agent-serve", "agentic-owners"),
   },
 });

package/templates/agentic-owners/agent/channels/github.ts

@@ -22,10 +22,8 @@ const REVIEW_ACTIONS = new Set([
 let log: (line: string) => void = () => {};
 
 export default githubChannel({
-  // With repos configured, the signed-in Cursor account supplies both the
-  // PR event stream and a repo-scoped GitHub credential — no webhook or
-  // GitHub App setup. Empty repos boots without the binding so a fresh
-  // scaffold's `dev` / `eval` run; use `agent-sdk github replay` there.
+  // Empty `repos` skips the Cursor GitHub binding so `dev` / `eval` boot
+  // on a fresh scaffold.
   cursorAccount: config.repos.length > 0 ? { repos: config.repos } : undefined,
   // The model never writes to GitHub; record_review actuates host-side.
   deliverReplies: false,
@@ -33,9 +31,7 @@ export default githubChannel({
     log = (line) => args.logger(`[agentic-owners] ${line}`);
   },
   onPullRequest: async (ctx, pr) => {
-    // A base retarget re-resolves the policy against the new base: the diff
-    // and the governing policy files both changed, so the old verdict — and
-    // any approval it produced — no longer covers this PR. The fresh
+    // A base retarget re-resolves policy against the new base. The fresh
     // actuation dismisses a leftover approve when the new decision holds.
     const baseRetargeted =
       pr.action === "edited" && pr.baseRefChangedFrom !== undefined;
@@ -54,9 +50,8 @@ export default githubChannel({
     try {
       const state = await loadReviewState(forge, log);
       if (!state.enrolled) {
-        // Enrollment can end while an agent approval is live (base retarget,
-        // owned files dropped); dismiss it instead of leaving it counting
-        // toward branch protection under a policy that never granted it.
+        // Enrollment can end while an agent approval is live; dismiss it
+        // instead of leaving it counting toward branch protection.
         return {
           task: () =>
             dismissStaleApprovals(
@@ -69,14 +64,10 @@ export default githubChannel({
         auth: defaultGitHubAuth(ctx),
         message: renderReviewWake(state),
         title: `Review ${ctx.repository.fullName}#${pr.number}`,
-        // Freeze the assessed head host-side: record_review reads this file
-        // instead of trusting a model-supplied SHA, so a mid-turn push (or a
-        // prompt-injected SHA) can never line up with the live head.
         workspaceFiles: { "pr/head.sha": state.pr.headSha },
       };
     } catch (error) {
       if (error instanceof AgenticOwnersConfigValidationError) {
-        // Fail closed but visibly: comment the issues, review nothing.
         return { task: () => reportPolicyError(forge, error) };
       }
       throw error;

package/templates/agentic-owners/agent/lib/config.ts

@@ -1,11 +1,3 @@
-/**
- * The one file to edit: which GitHub repositories the agent reviews.
- *
- * Setting it streams PR events and a repo-scoped GitHub credential through
- * your signed-in Cursor account (`agent-sdk login`) — no webhook or GitHub
- * App setup. While empty, the agent still runs locally against replayed
- * PRs (`agent-sdk github replay <pr-url>`).
- */
 const config = {
   repos: [] as string[], // e.g. ["acme/api"]
 };

package/templates/agentic-owners/agent/lib/review.ts

@@ -1,8 +1,5 @@
-// Policy resolution and actuation over the GitHub API — no repo checkout.
-// Every trusted input (policy files, rule prompts) is read from the PR's
-// **base ref**, so a PR cannot exempt itself by editing its own governance
-// files. Mirrors the Agentic Owners pipeline's `resolvePolicyForPr`, minus
-// the linguist-generated partition and content caching.
+// Policy files and rule prompts are read from the PR's base ref so a PR
+// cannot exempt itself by editing its own governance files.
 
 import {
   decideApproval,
@@ -297,12 +294,6 @@ export async function loadReviewState(
   };
 }
 
-/**
- * The model turn's wake message: composed rubric, PR context, and the
- * host-fetched diff. Fenced so author-controlled patch bytes cannot escape
- * into the trusted markdown (the fence outruns any backtick run inside the
- * patch).
- */
 /**
  * Filenames are author-controlled and render outside the diff fence: strip
  * control characters and backticks so a hostile path cannot fabricate
@@ -648,9 +639,6 @@ export async function actuateReview(input: {
   }).filter(
     (handle) => normalizeHandle(handle) !== normalizeHandle(pr.authorLogin ?? "")
   );
-  // The full decision — policy verdict plus the governance / evidence
-  // fail-closes — is computed in one place; from here on this function
-  // only writes.
   const decision = decideApproval({
     matchedRules: state.matchedRules,
     riskLevel: verdict.riskLevel,
@@ -742,7 +730,6 @@ export async function actuateReview(input: {
   const alreadyRequested = new Set(
     pr.requestedReviewers.map(normalizeHandle)
   );
-  // Adds fill only the remaining slots under the max-of-two rule.
   const newReviewers = decision.requestReviewers
     .filter((handle) => !alreadyRequested.has(normalizeHandle(handle)))
     .slice(

package/templates/agentic-owners/agent/tools/record_review.ts

@@ -41,10 +41,8 @@ export default defineTool({
           "not a GitHub pull-request session — reviews start from the github channel (agent-sdk github replay <pr-url> to test locally)",
       };
     }
-    // The channel wake froze the assessed head into the session workspace.
-    // Reading it here (instead of accepting a model-supplied SHA) means a
-    // mid-turn push can never line up with the live head: the actuation
-    // compares wake-observed against live and skips on any mismatch.
+    // Wake froze the assessed head into the session workspace. A model-supplied
+    // SHA is never trusted.
     let assessedHeadSha: string;
     try {
       assessedHeadSha = (

package/templates/demo/agent/agent.ts

@@ -1,18 +1,8 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  },
   tools: ["read", "grep"],
   local: {
     sandbox: true,
-    cwd: join(homedir(), ".cache", "agent-serve", "demo"),
   },
 });

package/templates/pr-autofixer/README.md

@@ -34,8 +34,6 @@ enables auto-merge, or force-pushes.
 GitHub wakes (`cursorAccount`) resume an already-driven PR on comment,
 review, and failing CI. They do not start a session on `pull_request.opened`.
 
-Affinity and the webhook buffer live in `host.kv` (`agent/storage.ts`).
-
 ## Files to edit
 
 - `agent/lib/repos.ts`: repos Cursor relays SCM events for

package/templates/pr-autofixer/agent/agent.ts

@@ -1,19 +1,8 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { defineAgent } from "@cursor/july";
 
 export default defineAgent({
-  model: {
-    id: "grok-4.5",
-    params: [
-      { id: "effort", value: "high" },
-      { id: "fast", value: "true" },
-    ],
-  },
-  runtime: "local",
   local: {
     sandbox: true,
-    cwd: join(homedir(), ".cache", "agent-serve", "pr-autofixer"),
   },
   cloud: {
     env: { type: "cloud" },

package/templates/pr-autofixer/agent/channels/slack.ts

@@ -1,12 +1,5 @@
 import { slackChannel } from "@cursor/july/channels/slack";
 
-/**
- * Slack channel (Socket Mode).
- *
- * Tokens: PR_AUTOFIXER_SLACK_BOT_TOKEN + PR_AUTOFIXER_SLACK_APP_TOKEN
- *
- * Full setup: agent-sdk slack create
- */
 export default slackChannel({
   envPrefix: "PR_AUTOFIXER",
   suggestedPromptsTitle: "Try asking",