@cursor/july 0.1.80 → 0.1.83

package/src/internal/skills-sync.ts

@@ -0,0 +1,110 @@
+/**
+ * Sync authored skills onto an Agent Store so cloud-runtime turns discover
+ * them natively. Hosted deployments write store-root `skills/<name>/…` (the
+ * VM's `--agent-store-skills-dir /cursor/stores/deployment/skills`). Local
+ * `serve`/`run` with `runtime: "cloud"` writes
+ * `agent-serve/<agent>/skills/<name>/…` on the 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[];
+  /** Store-root directory that holds SKILL.md files. Defaults to `skills/`. */
+  skillsPrefix?: string;
+}): Promise<void> {
+  const skillsPrefix = args.skillsPrefix ?? agentStoreKeys.skillsPrefix();
+  const desired = new Map<string, Uint8Array>();
+  for (const skill of args.skills) {
+    const key = (relPath: string): string =>
+      agentStoreKeys.skillFile(skill.name, relPath, skillsPrefix);
+    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(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);
+}

package/src/types.ts

@@ -11,9 +11,21 @@
 import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
+import type {
+  ContinuationClaim,
+  ContinuationIdentity,
+  MailboxContinuation,
+} from "./continuation.js";
 import type { OtelConfig, OtelDefinition } from "./otel.js";
 import type { StorageDefinition } from "./storage.js";
 
+export type {
+  ContinuationClaim,
+  ContinuationIdentity,
+  ConversationType,
+  MailboxContinuation,
+} from "./continuation.js";
+
 // ============================================================================
 // JSON
 // ============================================================================
@@ -240,8 +252,26 @@ export interface AgentConfig {
    * it only shapes what the model can call.
    */
   tools?: ToolName[];
+  /**
+   * Hosted architecture this agent deploys onto. Omit or `"v1"` keeps the
+   * current control plane and engine-minted conversation keys. `"v2"`
+   * deploys onto the v2 control plane (v2 APIs and schemas). Omitted
+   * channel `continuation` then inherits from declared events (`github.pr/v2`,
+   * `github.issue/v2`, `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
+   * `none/v2`). An explicit per-channel selector still overrides.
+   *
+   * ```ts
+   * export default defineAgent({
+   *   architecture: "v2",
+   * });
+   * ```
+   */
+  architecture?: AgentArchitecture;
 }
 
+/** Hosted architecture on {@link AgentConfig.architecture}. */
+export type AgentArchitecture = "v1" | "v2";
+
 /**
  * Built-in tools on {@link AgentConfig.builtinTools}. Each enabled
  * capability materializes as ordinary server tools at discovery time, so
@@ -1595,8 +1625,21 @@ export interface SendMessageOptions {
    * Channel-local continuation token. When it addresses an existing session
    * the message is a follow-up; otherwise a new session is created keyed by
    * this token. Omit to always create a fresh session.
+   *
+   * `/v2` selectors refuse this field — pass {@link mailboxContinuation} or
+   * a structured {@link claim} instead.
    */
   continuationToken?: string;
+  /**
+   * v2 mailbox stamp from the control plane (or the pack's builtin extract
+   * on local serve). Ignored on v1.
+   */
+  mailboxContinuation?: MailboxContinuation;
+  /**
+   * v2 host join. Never a concatenated `pr:owner/repo#N` string — the
+   * registry mints `cont:` bytes from this claim.
+   */
+  claim?: ContinuationClaim;
   /** Initial channel state for newly created sessions. */
   state?: JsonValue;
   /**
@@ -2057,6 +2100,12 @@ export type ChannelDefinition<TState = JsonValue> = ChannelConfig<TState> &
 export interface HttpChannelConfig {
   /** Route auth chain. Defaults to `[localDevStrict()]`. */
   auth?: AuthPolicy[];
+  /**
+   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+   * `"none/v1"` unless the agent set `architecture: "v2"` (then `"none/v2"`
+   * → `evt:`). Override with an explicit `"none/v1"` or `"none/v2"`.
+   */
+  continuation?: ContinuationIdentity;
   /**
    * Transform the inbound message before the agent sees it (e.g. prepend
    * request-specific context).
@@ -2549,6 +2598,12 @@ export interface ResolvedAgent {
   hosting?: AgentHostingOptions;
   /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
   concurrency?: AgentConcurrencyOptions;
+  /**
+   * Validated architecture from {@link AgentConfig.architecture}.
+   * `"v2"` deploys onto the v2 control plane and stamps kind `/v2`
+   * continuation defaults onto channels that omitted a selector.
+   */
+  architecture?: AgentArchitecture;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
@@ -2714,6 +2769,11 @@ export interface RunnerTurnRequest {
   runtime: AgentRuntime;
   /** Cloud options when {@link runtime} is `"cloud"`. */
   cloud?: AgentCloudOptions;
+  /**
+   * defineAgent directory slug for personal-key cloud creates. Injected
+   * by the engine — not part of authored {@link AgentCloudOptions}.
+   */
+  agentServeAgent?: string;
   /** In-process tools, already bound to the session's tool context. */
   customTools: Record<string, SDKCustomTool>;
   /** MCP servers from `agent/mcp-connections/`. */