@cursor/july 0.1.80 → 0.1.83

package/src/internal/discovery.ts

@@ -23,6 +23,7 @@ import { httpChannel } from "../channels.js";
 import type { OtelDefinition } from "../otel.js";
 import type { StorageDefinition } from "../storage.js";
 import {
+  type AgentArchitecture,
   type AgentConcurrencyOptions,
   type AgentConfigDefinition,
   type AgentHostingOptions,
@@ -68,6 +69,7 @@ import {
   builtinTools,
   TAG_ARTIFACT_TOOL_NAME,
 } from "./builtin-tools/index.js";
+import { applyAgentContinuationDefaults } from "./continuation-channel.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import {
@@ -311,12 +313,19 @@ export async function loadAgentProject(
     await warnUnknownSlots(ctx, agentDir);
   }
 
+  const resolvedHttpChannel = httpChannelDefinition ?? httpChannel();
+  applyAgentContinuationDefaults({
+    agent,
+    channels,
+    httpChannel: resolvedHttpChannel,
+  });
+
   return {
     rootDir,
     agentDir,
     name: agent.name,
     agent,
-    httpChannel: httpChannelDefinition ?? httpChannel(),
+    httpChannel: resolvedHttpChannel,
     channels,
     schedules,
     hooks,
@@ -387,6 +396,13 @@ async function loadAgent(
           "tools is not supported on subagents (they keep the harness task-tool toolset); ignoring.",
       });
     }
+    if (config?.architecture !== undefined) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        path: displayPath(ctx, join(agentDir, "agent.ts")),
+        message: "architecture is not supported on subagents; ignoring.",
+      });
+    }
     const artifactsPath = await findModuleFile(agentDir, "artifacts");
     if (artifactsPath !== undefined) {
       ctx.diagnostics.push({
@@ -505,6 +521,7 @@ async function loadAgent(
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
+  const architecture = resolveArchitecture(ctx, agentDir, config?.architecture);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -529,6 +546,7 @@ async function loadAgent(
     ...(allowedTools === undefined ? {} : { allowedTools }),
     hosting,
     concurrency,
+    ...(architecture === undefined ? {} : { architecture }),
     tools,
     skills,
     connections,
@@ -537,6 +555,26 @@ async function loadAgent(
   };
 }
 
+function resolveArchitecture(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  architecture: AgentArchitecture | undefined
+): AgentArchitecture | undefined {
+  if (
+    architecture === undefined ||
+    architecture === "v1" ||
+    architecture === "v2"
+  ) {
+    return architecture;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, join(agentDir, "agent.ts")),
+    message: `architecture must be "v1" or "v2"; got ${JSON.stringify(architecture)}.`,
+  });
+  return undefined;
+}
+
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(
   ctx: DiscoveryContext,
@@ -1549,7 +1587,7 @@ function warnCloudRuntimeLimitations(
       severity: "warning",
       path: displayPath(ctx, join(agentDir, "skills")),
       message:
-        "Authored skills are materialized into the local session workspace only; cloud agents see skills that already exist in the cloud repo.",
+        "Authored skills reach cloud agents through native store discovery: hosted deployments write the deployment store's skills/ directory; local serve/run with a personal API key writes agent-serve/<agent>/skills/ on the USER store. Without a reachable store, only skills already in the cloud repo are visible.",
     });
   }
   if (counts.seedFiles > 0) {

package/src/internal/sdk-runner.ts

@@ -514,7 +514,7 @@ export class CursorSdkRunner implements AgentRunner {
     request: RunnerTurnRequest,
     shared: Pick<AgentOptions, "model" | "apiKey" | "mcpServers" | "agents">
   ): Promise<SDKAgent> {
-    const cloud = toCloudAgentOptions(request.cloud);
+    const cloud = toCloudAgentOptions(request.cloud, request.agentServeAgent);
     const hasEnvVars =
       cloud.envVars !== undefined && Object.keys(cloud.envVars).length > 0;
     const options: AgentOptions = {
@@ -603,24 +603,23 @@ export function toModelSelection(model: ModelSetting): ModelSelection {
 }
 
 function toCloudAgentOptions(
-  cloud: RunnerTurnRequest["cloud"]
+  cloud: RunnerTurnRequest["cloud"],
+  agentServeAgent?: string
 ): CloudAgentOptions {
-  if (cloud === undefined) {
-    return {};
-  }
   return {
-    ...(cloud.env === undefined ? {} : { env: cloud.env }),
-    ...(cloud.repos === undefined ? {} : { repos: cloud.repos }),
-    ...(cloud.workOnCurrentBranch === undefined
+    ...(cloud?.env === undefined ? {} : { env: cloud.env }),
+    ...(cloud?.repos === undefined ? {} : { repos: cloud.repos }),
+    ...(cloud?.workOnCurrentBranch === undefined
       ? {}
       : { workOnCurrentBranch: cloud.workOnCurrentBranch }),
-    ...(cloud.autoCreatePR === undefined
+    ...(cloud?.autoCreatePR === undefined
       ? {}
       : { autoCreatePR: cloud.autoCreatePR }),
-    ...(cloud.skipReviewerRequest === undefined
+    ...(cloud?.skipReviewerRequest === undefined
       ? {}
       : { skipReviewerRequest: cloud.skipReviewerRequest }),
-    ...(cloud.envVars === undefined ? {} : { envVars: cloud.envVars }),
+    ...(cloud?.envVars === undefined ? {} : { envVars: cloud.envVars }),
+    ...(agentServeAgent === undefined ? {} : { agentServeAgent }),
   };
 }
 

package/src/internal/server.ts

@@ -20,8 +20,10 @@ import {
 } from "../channels/deployments/deployments-channel.js";
 import type { DeploymentsChannelOptions } from "../channels/deployments/types.js";
 import {
+  type CursorAccountGithubTokenResolver,
   type CursorGithubRepoScope,
   createCursorAccountGithubTokenResolver,
+  createCursorGithubProxyHostResolver,
   cursorGithubPermissionsForChannel,
   type GithubCursorAccountRuntime,
   getGithubCursorAccountRuntime,
@@ -316,6 +318,10 @@ export async function startServer(
       : requireCursorEventsAuth(effectiveCursorEvents, accountKey);
 
   let cursorGithubCredentials: CursorGithubCredentialProvider | undefined;
+  // Proxy-wired GitHub token resolver for `ctx.host.github` when no startup
+  // token mint runs (empty repo scope): host Octokit calls must route
+  // through github-proxy exactly like channel Octokit calls.
+  let hostGithubProxyResolver: CursorAccountGithubTokenResolver | undefined;
   if (cursorGithubTargets.length > 0) {
     const githubProxyRequested = options.cursorGithubProxy === true;
     const needsGithubAuth =
@@ -408,23 +414,31 @@ export async function startServer(
           );
           target.accountRuntime.credentials.bindProxyTransport(proxyTransport);
         }
+        // `ctx.host.github` gets the same proxy transport; without this it
+        // would fall back to ambient auth (env token / `gh`) or an
+        // unauthenticated Octokit, and every host GitHub call would 404.
+        hostGithubProxyResolver = createCursorGithubProxyHostResolver({
+          getApiKey: async () => cursorGithubAuth.apiKey,
+          transport: proxyTransport,
+        });
         logger(
-          `[agent-sdk] GitHub auth: channel API calls route through ${githubProxyUrl} (repo scope per request)`
+          `[agent-sdk] GitHub auth: channel and host API calls route through ${githubProxyUrl} (repo scope per request)`
         );
       }
     }
   }
   const resolvedCursorGithubCredentials = cursorGithubCredentials;
+  const hostGithubToken =
+    hostGithubProxyResolver ??
+    (resolvedCursorGithubCredentials === undefined
+      ? undefined
+      : createCursorAccountGithubTokenResolver(() =>
+          resolvedCursorGithubCredentials.getToken()
+        ));
   const hostPlatforms = createHostPlatforms(
-    resolvedCursorGithubCredentials === undefined
+    hostGithubToken === undefined
       ? {}
-      : {
-          githubCredentials: {
-            token: createCursorAccountGithubTokenResolver(() =>
-              resolvedCursorGithubCredentials.getToken()
-            ),
-          },
-        }
+      : { githubCredentials: { token: hostGithubToken } }
   );
 
   if (playground) {

package/src/internal/session-engine.ts

@@ -24,7 +24,15 @@ import {
   SlackNudgeStore,
 } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
-import { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
+import {
+  AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+  agentStoreKeys,
+} from "../files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+  isCursorUserStoreFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -80,6 +88,16 @@ import {
   isUnpricedCompletedTurn,
   mapSdkTokenUsage,
 } from "./cloud-turn-cost.js";
+import {
+  applyAgentContinuationDefaults,
+  channelContinuationIdentity,
+  httpContinuationIdentity,
+} from "./continuation-channel.js";
+import {
+  continuationSource,
+  resolveV2Key,
+  V2EngineError,
+} from "./continuation-identity.js";
 import { isDevMode } from "./dev-mode.js";
 import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
@@ -113,6 +131,7 @@ import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections
 import type { AgentRunner } from "./sdk-runner.js";
 import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
+import { syncSkillsToStore } from "./skills-sync.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
@@ -302,6 +321,8 @@ export class SessionEngine {
   >();
   /** Once-per-process cache for the A/B snapshot backfill (see abSnapshot). */
   private restoredAbSnapshot: Promise<ABSnapshot | undefined> | undefined;
+  /** In-flight skills → Agent Store sync (see ensureCloudSkillsSynced). */
+  private cloudSkillsSync: Promise<boolean> | undefined;
 
   private readonly runner: AgentRunner;
   private readonly logger: (line: string) => void;
@@ -366,6 +387,7 @@ export class SessionEngine {
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
+    applyAgentContinuationDefaults(this.project);
     this.stateRoot = options.stateRoot;
     this.runner = options.runner;
     this.logger = options.logger ?? (() => {});
@@ -734,26 +756,50 @@ export class SessionEngine {
    * Start or resume a session on a channel. When `continuationToken`
    * addresses an existing session this is a follow-up turn; otherwise a new
    * session is created (keyed by the provided token, or a fresh one).
+   *
+   * v2 (`/v2` selectors) refuses `continuationToken` and looks
+   * up `(agentId, cKey)` from a mailbox stamp or structured claim.
    */
   async send(
     channelId: string,
     message: string,
     options: EngineSendOptions = {}
   ): Promise<ChannelSession> {
-    const auth = options.auth ?? null;
+    const identity =
+      channelId === HTTP_CHANNEL_ID
+        ? httpContinuationIdentity(this.project.httpChannel)
+        : channelContinuationIdentity(this.channelsById.get(channelId));
+    let sendOptions = options;
+    let skipContinuationLookup = false;
+    if (continuationSource(identity) === "control-plane") {
+      if (options.continuationToken !== undefined) {
+        throw new V2EngineError(
+          "v2: do not pass continuationToken; use mailboxContinuation or claim"
+        );
+      }
+      const cKey = resolveV2Key(identity, options);
+      sendOptions = { ...options, continuationToken: cKey };
+      skipContinuationLookup = cKey.startsWith("evt:");
+    }
+
+    const auth = sendOptions.auth ?? null;
     let existing =
-      options.continuationToken === undefined
+      skipContinuationLookup || sendOptions.continuationToken === undefined
         ? undefined
         : await this.sessions.findByContinuation(
             channelId,
-            options.continuationToken
+            sendOptions.continuationToken
           );
-    if (existing === undefined && options.continuationToken !== undefined) {
+    if (
+      existing === undefined &&
+      !skipContinuationLookup &&
+      sendOptions.continuationToken !== undefined
+    ) {
       // Local miss: the session may live only in the storage sink (it
       // fell outside the startup restore window, or restore is lazy-only).
       existing = await this.restoreSessionByContinuation(
         channelId,
-        options.continuationToken
+        sendOptions.continuationToken
       );
     }
 
@@ -765,25 +811,25 @@ export class SessionEngine {
       // synchronize). Leave the durable continuation key unchanged.
       let record = existing;
       const refreshWorkspace =
-        options.workspaceDir !== undefined &&
-        options.workspaceDir !== existing.workspaceOverride;
+        sendOptions.workspaceDir !== undefined &&
+        sendOptions.workspaceDir !== existing.workspaceOverride;
       if (
         refreshWorkspace ||
-        options.workspaceFiles !== undefined ||
-        options.images !== undefined
+        sendOptions.workspaceFiles !== undefined ||
+        sendOptions.images !== undefined
       ) {
         record = await this.updateRecord(existing.sessionId, (current) => ({
           ...current,
           workspaceOverride: refreshWorkspace
-            ? options.workspaceDir
+            ? sendOptions.workspaceDir
             : current.workspaceOverride,
           pendingWorkspaceFiles: mergePendingWorkspaceFiles(
             current.pendingWorkspaceFiles,
-            options.workspaceFiles
+            sendOptions.workspaceFiles
           ),
           pendingImages: mergePendingImages(
             current.pendingImages,
-            options.images
+            sendOptions.images
           ),
         }));
       }
@@ -792,31 +838,32 @@ export class SessionEngine {
       // and the first send's snapshot must not pin this session's turns to a
       // stale repo/prUrl for the session's lifetime.
       if (
-        options.cloud !== undefined &&
-        JSON.stringify(options.cloud) !== JSON.stringify(record.cloudOverride)
+        sendOptions.cloud !== undefined &&
+        JSON.stringify(sendOptions.cloud) !==
+          JSON.stringify(record.cloudOverride)
       ) {
         record = await this.updateRecord(record.sessionId, (current) => ({
           ...current,
-          cloudOverride: options.cloud,
+          cloudOverride: sendOptions.cloud,
         }));
       }
       // Refresh wake-derived channel state (GitHub headSha / refs) without
       // wiping sticky fields. Null patch values are skipped.
-      if (options.refreshState !== undefined) {
+      if (sendOptions.refreshState !== undefined) {
         record = await this.updateRecord(record.sessionId, (current) => ({
           ...current,
           channelState: mergeChannelStateSkipNull(
             current.channelState,
-            options.refreshState
+            sendOptions.refreshState
           ),
         }));
       }
       const since = (await this.logs.get(record.sessionId)).count;
       const coalesced = await this.startTurn(record.sessionId, message, {
-        admission: options.admission ?? "preempt",
-        ...(options.coalesceSourceTs === undefined
+        admission: sendOptions.admission ?? "preempt",
+        ...(sendOptions.coalesceSourceTs === undefined
           ? {}
-          : { sourceTs: options.coalesceSourceTs }),
+          : { sourceTs: sendOptions.coalesceSourceTs }),
       });
       return this.channelSession(
         record.sessionId,
@@ -828,22 +875,22 @@ export class SessionEngine {
     }
 
     const now = new Date().toISOString();
-    const channelState = this.initialChannelState(channelId, options.state);
-    const purpose = options.purpose === "eval" ? "eval" : "live";
+    const channelState = this.initialChannelState(channelId, sendOptions.state);
+    const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
     let record: SessionRecord = {
       sessionId: newSessionId(),
       channelId,
-      mode: options.mode ?? "chat",
+      mode: sendOptions.mode ?? "chat",
       purpose,
-      continuationKey: options.continuationToken ?? newContinuationKey(),
+      continuationKey: sendOptions.continuationToken ?? newContinuationKey(),
       auth,
-      title: options.title,
+      title: sendOptions.title,
       channelState,
-      workspaceOverride: options.workspaceDir,
-      pendingWorkspaceFiles: options.workspaceFiles,
-      pendingImages: options.images,
-      cloudOverride: options.cloud,
-      sdkAgentId: options.sdkAgentId,
+      workspaceOverride: sendOptions.workspaceDir,
+      pendingWorkspaceFiles: sendOptions.workspaceFiles,
+      pendingImages: sendOptions.images,
+      cloudOverride: sendOptions.cloud,
+      sdkAgentId: sendOptions.sdkAgentId,
       turnCount: 0,
       createdAt: now,
       updatedAt: now,
@@ -857,10 +904,10 @@ export class SessionEngine {
     record = await this.enrollABs(record);
     const since = (await this.logs.get(record.sessionId)).count;
     await this.startTurn(record.sessionId, message, {
-      admission: options.admission ?? "preempt",
-      ...(options.coalesceSourceTs === undefined
+      admission: sendOptions.admission ?? "preempt",
+      ...(sendOptions.coalesceSourceTs === undefined
         ? {}
-        : { sourceTs: options.coalesceSourceTs }),
+        : { sourceTs: sendOptions.coalesceSourceTs }),
     });
     return this.channelSession(record.sessionId, record, true, false, since);
   }
@@ -1753,6 +1800,88 @@ export class SessionEngine {
     };
   }
 
+  /**
+   * Sync authored skills onto the Agent Store at `skills/<name>/…` (hosted)
+   * or `agent-serve/<agent>/skills/<name>/…` (personal-key local+cloud)
+   * before the first cloud prompt, so `--agent-store-skills-dir` and the
+   * first-turn S3 scan can discover them. False when the sync fails: the
+   * turn then runs without store skills rather than pointing discovery at
+   * paths that do not exist.
+   *
+   * With skills authored, every first cloud turn re-copies the authored
+   * bytes and the memo only dedupes concurrent first turns. The mount is
+   * writable from cloud sessions, so a once-per-process copy would let one
+   * session's edits masquerade as agent definition for every later session
+   * until the engine restarts; re-syncing keeps the store true to discovery
+   * the same way local materialization always rewrites skills. Without
+   * skills the sync is best-effort stale cleanup and one attempt per
+   * process is enough, success or not — a deployment without the files
+   * surface must not fail and log on every new session for a feature it
+   * does not use.
+   */
+  private ensureCloudSkillsSynced(): Promise<boolean> {
+    if (this.cloudSkillsSync !== undefined) {
+      return this.cloudSkillsSync;
+    }
+    const target = this.cloudSkillsStore();
+    if (target === undefined) {
+      this.cloudSkillsSync = Promise.resolve(false);
+      return this.cloudSkillsSync;
+    }
+    const skills = this.project.agent.skills;
+    let sync = syncSkillsToStore({
+      sink: target.sink,
+      agentName: this.project.name,
+      skills,
+      skillsPrefix: target.skillsPrefix,
+    }).then(
+      () => true,
+      (error) => {
+        this.logger(
+          `[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+        return false;
+      }
+    );
+    if (skills.length > 0) {
+      sync = sync.finally(() => {
+        this.cloudSkillsSync = undefined;
+      });
+    }
+    this.cloudSkillsSync = sync;
+    return sync;
+  }
+
+  /**
+   * Hosted deployments own the deployment store. Local `serve`/`run` with
+   * a personal API key writes into the USER store under `agent-serve/`.
+   */
+  private cloudSkillsStore():
+    | {
+        sink: ReturnType<typeof cursorHostedFiles>;
+        skillsPrefix: string;
+        label: string;
+      }
+    | undefined {
+    if (isCursorHostedFilesAvailable()) {
+      return {
+        sink: cursorHostedFiles(),
+        skillsPrefix: agentStoreKeys.skillsPrefix(),
+        label: "deployment store",
+      };
+    }
+    if (isCursorUserStoreFilesAvailable()) {
+      return {
+        sink: cursorHostedFiles({
+          storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+        }),
+        skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+        label: "user store",
+      };
+    }
+    return undefined;
+  }
+
   private async buildTurnRequest(
     record: SessionRecord,
     agent: ResolvedAgent,
@@ -1815,8 +1944,9 @@ export class SessionEngine {
     if (isFirstTurn) {
       if (runtime === "cloud") {
         // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies. On hosted deployments the
-        // shared memory journal is on the store mount — say where. When the
+        // including agent tool script bodies. On hosted deployments authored
+        // skills land on the store mount for native discovery, and the
+        // shared memory journal is on that mount too — say where. When the
         // turn carries the session-bound server-tool MCP endpoint, the
         // preamble catalogs server tools under that MCP server name *before*
         // the agent-tool "write the script if missing" recipe, so a model
@@ -1828,7 +1958,15 @@ export class SessionEngine {
               ? undefined
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
-        const memorySection = isCursorHostedFilesAvailable()
+        const hosted = isCursorHostedFilesAvailable();
+        // Synced whenever a store is reachable, not just when skills exist:
+        // removing the last skill has to delete its store copies too.
+        // Discovery is native (`--agent-store-skills-dir`); this only has
+        // to land the bytes.
+        if (hosted || isCursorUserStoreFilesAvailable()) {
+          await this.ensureCloudSkillsSynced();
+        }
+        const memorySection = hosted
           ? `\n\n${buildCloudMemorySection(this.project.name)}`
           : "";
         turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
@@ -1859,6 +1997,9 @@ export class SessionEngine {
       ...(agent.model === undefined ? {} : { model: agent.model }),
       runtime,
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
+      ...(runtime === "cloud" && !isCursorHostedFilesAvailable()
+        ? { agentServeAgent: this.project.name }
+        : {}),
       customTools:
         runtime === "local"
           ? await this.buildCustomTools(record, agent, turnId, emit)

package/src/internal/session-store.ts

@@ -11,6 +11,7 @@ import { mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { SessionRecord } from "../types.js";
 import { isSafeSessionId } from "./auth.js";
+import { isV2DurableContinuationKey } from "./continuation-identity.js";
 
 export class SessionStore {
   private readonly cache = new Map<string, SessionRecord>();
@@ -39,6 +40,11 @@ export class SessionStore {
   }
 
   private continuationKeyOf(channelId: string, key: string): string {
+    // v2 index is (agentId, cKey). This store is already per-agent, so drop
+    // channelId for `cont:` / `evt:` keys. v1 stays `{channelId}\n{token}`.
+    if (isV2DurableContinuationKey(key)) {
+      return `\0v2\n${key}`;
+    }
     return `${channelId}\n${key}`;
   }