@cursor/july 0.1.80 → 0.1.82

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 on hosted deployments via the deployment store's skills/ directory (native skill discovery). Cloud turns started outside hosting (dev serve/run) see only skills already in the cloud repo.",
     });
   }
   if (counts.seedFiles > 0) {

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,10 @@ 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 {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
 import {
   type AgentProject,
   type ApprovalDecision,
@@ -80,6 +83,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 +126,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 +316,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 → deployment store sync (see ensureCloudSkillsSynced). */
+  private cloudSkillsSync: Promise<boolean> | undefined;
 
   private readonly runner: AgentRunner;
   private readonly logger: (line: string) => void;
@@ -366,6 +382,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 +751,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 +806,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 +833,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 +870,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 +899,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 +1795,51 @@ export class SessionEngine {
     };
   }
 
+  /**
+   * Sync authored skills onto the deployment store at `skills/<name>/…`
+   * 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 skills = this.project.agent.skills;
+    let sync = syncSkillsToStore({
+      sink: cursorHostedFiles(),
+      agentName: this.project.name,
+      skills,
+    }).then(
+      () => true,
+      (error) => {
+        this.logger(
+          `[skills] deployment store 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;
+  }
+
   private async buildTurnRequest(
     record: SessionRecord,
     agent: ResolvedAgent,
@@ -1815,8 +1902,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 +1916,14 @@ export class SessionEngine {
               ? undefined
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
-        const memorySection = isCursorHostedFilesAvailable()
+        const hosted = isCursorHostedFilesAvailable();
+        // Synced whenever hosted, 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) {
+          await this.ensureCloudSkillsSynced();
+        }
+        const memorySection = hosted
           ? `\n\n${buildCloudMemorySection(this.project.name)}`
           : "";
         turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;

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}`;
   }
 

package/src/internal/skills-sync.ts

@@ -0,0 +1,107 @@
+/**
+ * Sync authored skills into the deployment's Agent Store so cloud-runtime
+ * turns discover them natively. The engine writes through the hosted sink
+ * at store-root `skills/<name>/…`; the cloud VM is launched with
+ * `--agent-store-skills-dir /cursor/stores/deployment/skills` and walks that
+ * directory the same way it walks a user store.
+ */
+
+import { readFile } from "node:fs/promises";
+import { posix } from "node:path";
+import { agentStoreKeys, FileConflictError, type FileSink } from "../files.js";
+import { STORAGE_KEY_ROOT } from "../storage.js";
+import type { DiscoveredSkill, SkillFileSource } from "../types.js";
+import { buildSkillMd } from "./workspace.js";
+
+/** Pre-native layout. Deleted on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
+function legacySkillsPrefix(agent: string): string {
+  return `${STORAGE_KEY_ROOT}/${agent}/skills/`;
+}
+
+/**
+ * Mirror the agent's skills onto the store: write every SKILL.md (with the
+ * same generated frontmatter local materialization uses) plus sibling files,
+ * and delete keys no authored skill claims so redeploys drop removed skills.
+ *
+ * Everything loads and validates before the store is touched, and writes
+ * land before stale deletes, so a failed sync never leaves a gap a
+ * concurrent cloud reader could see.
+ */
+export async function syncSkillsToStore(args: {
+  sink: FileSink;
+  /** Sweeps leftover keys from the pre-native `agentkit/v1/{agent}/skills/` prefix. */
+  agentName: string;
+  skills: readonly DiscoveredSkill[];
+}): Promise<void> {
+  const desired = new Map<string, Uint8Array>();
+  for (const skill of args.skills) {
+    const key = (relPath: string): string =>
+      agentStoreKeys.skillFile(skill.name, relPath);
+    desired.set(key("SKILL.md"), Buffer.from(buildSkillMd(skill), "utf8"));
+    for (const [relPath, source] of Object.entries(skill.files)) {
+      desired.set(key(storeRelPath(relPath)), await sourceBytes(source));
+    }
+  }
+  await Promise.all(
+    [...desired].map(([key, body]) => putLastWriterWins(args.sink, key, body))
+  );
+  const [existing, leftover] = await Promise.all([
+    args.sink.list(agentStoreKeys.skillsPrefix()),
+    args.sink.list(legacySkillsPrefix(args.agentName)),
+  ]);
+  await Promise.all(
+    [...existing.filter((entry) => !desired.has(entry.key)), ...leftover].map(
+      (entry) => args.sink.delete(entry.key)
+    )
+  );
+}
+
+/**
+ * Same refusals as local materialization's `resolveInside`: a rel that
+ * escapes the skill directory or would not round-trip through the FUSE
+ * mount (`..`, `.`, `//`, absolute) fails the sync, exactly as it fails a
+ * local turn's workspace write. Backslashes are refused too — the store
+ * normalizes `\` to `/` on write, so the stored key would differ from the
+ * desired one and the stale pass would delete the file it just wrote.
+ */
+function storeRelPath(relPath: string): string {
+  if (
+    relPath.includes("\0") ||
+    relPath.includes("\\") ||
+    posix.isAbsolute(relPath) ||
+    relPath.endsWith("/") ||
+    relPath.split("/").some((seg) => seg === ".." || seg === ".") ||
+    posix.normalize(relPath) !== relPath
+  ) {
+    throw new Error(
+      `Refusing skill file path "${relPath}" (must be a normalized relative path)`
+    );
+  }
+  return relPath;
+}
+
+/**
+ * Last writer wins. A raced conditional put (dual engine pods during a
+ * deploy rollover) clears the sink's cached etag, so one retry re-learns
+ * the current version and lands.
+ */
+async function putLastWriterWins(
+  sink: FileSink,
+  key: string,
+  body: Uint8Array
+): Promise<void> {
+  try {
+    await sink.put(key, body);
+  } catch (error) {
+    if (!(error instanceof FileConflictError)) {
+      throw error;
+    }
+    await sink.put(key, body);
+  }
+}
+
+async function sourceBytes(source: SkillFileSource): Promise<Uint8Array> {
+  return "contents" in source
+    ? Buffer.from(source.contents, "utf8")
+    : readFile(source.sourcePath);
+}