@cursor/july 0.1.101 → 0.1.103

package/src/internal/skills-sync.ts

@@ -7,10 +7,10 @@
  */
 
 import { readFile } from "node:fs/promises";
-import { posix } from "node:path";
-import { agentStoreKeys, FileConflictError, type FileSink } from "../files.js";
+import { agentStoreKeys, type FileSink } from "../files.js";
 import { STORAGE_KEY_ROOT } from "../storage.js";
 import type { DiscoveredSkill, SkillFileSource } from "../types.js";
+import { mirrorToStore, storeRelPath } from "./store-mirror.js";
 import { buildSkillMd } from "./workspace.js";
 
 /** Pre-native layout. Deleted on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
@@ -22,10 +22,7 @@ function legacySkillsPrefix(agent: string): string {
  * 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.
+ * Everything loads and validates before the store is touched.
  */
 export async function syncSkillsToStore(args: {
   sink: FileSink;
@@ -42,65 +39,18 @@ export async function syncSkillsToStore(args: {
       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));
+      desired.set(
+        key(storeRelPath(relPath, "skill file")),
+        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);
-  }
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: skillsPrefix,
+    desired,
+    legacyPrefixes: [legacySkillsPrefix(args.agentName)],
+  });
 }
 
 async function sourceBytes(source: SkillFileSource): Promise<Uint8Array> {

package/src/internal/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/internal/start-log-store.ts

@@ -8,21 +8,18 @@
  * after park/discard.
  *
  * Same flush moments as `hosted-execution.json` and session-runs —
- * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.log}.
+ * see `hosted-execution-flush.ts`. Keys: {@link agentSdkStorageKeys.log}.
  * Values are raw UTF-8, not JSON.
  */
 
 import { readFile } from "node:fs/promises";
 import type { FileSink } from "../files.js";
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
-import { storageKeys } from "../storage-protocol.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
+import { agentSdkStorageKeys } from "../storage-protocol.js";
 import type { AgentProject } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import { describeError } from "./describe-error.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 /**
  * Last N bytes flushed to the store. Matches the Temporal catch-up cap
@@ -102,7 +99,7 @@ export function createStartLogStore(input: {
 
   return {
     async persist(startLogId, contents) {
-      const key = storageKeys.log(agentName, startLogId);
+      const key = agentSdkStorageKeys.log(agentName, startLogId);
       const body = tailStartLogText(contents, START_LOG_STORE_MAX_BYTES);
       try {
         await sink.put(key, new TextEncoder().encode(body));
@@ -114,7 +111,7 @@ export function createStartLogStore(input: {
     },
 
     async read(startLogId) {
-      const key = storageKeys.log(agentName, startLogId);
+      const key = agentSdkStorageKeys.log(agentName, startLogId);
       try {
         const body = await sink.get(key);
         if (body === undefined) {
@@ -140,17 +137,17 @@ export function selectStartLogStore(input: {
   logger?: (line: string) => void;
   env?: Record<string, string | undefined>;
 }): StartLogStore | undefined {
-  if (input.project.agent.architecture !== "v2") {
-    return undefined;
-  }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.project.agent.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     return undefined;
   }
-  const envSnapshot = env as NodeJS.ProcessEnv;
   return createStartLogStore({
     sink: cursorHostedFiles({
-      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveStoreSourceId: () =>
+        hosting.resolveStoreIds().frameworkStoreSourceId,
       resolveApiKey: () => resolveApiKeySync()?.apiKey,
     }),
     agentName: input.project.name,

package/src/internal/storage-coordinator.ts

@@ -31,6 +31,7 @@ import {
   type StorageContext,
   type StorageDefinition,
   type StorageEntry,
+  type StorageKeys,
   storageKeys,
 } from "../storage.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
@@ -79,7 +80,7 @@ const AB_SNAPSHOT_MIN_INTERVAL_MS = 60_000;
 
 /** One queued sink call (KV put/delete or a dedicated-table write). */
 interface StorageOp {
-  /** Human-readable op label for failure logs, e.g. `put(agentkit/v1/...)`. */
+  /** Human-readable op label for failure logs, e.g. `put({root}/...)`. */
   label: string;
   run: (ctx: StorageContext) => void | Promise<void>;
 }
@@ -89,6 +90,8 @@ export interface StorageCoordinatorOptions {
   agentName: string;
   projectRoot: string;
   logger: (line: string) => void;
+  /** Defaults to the architecture-v1 key contract. */
+  keys?: StorageKeys;
 }
 
 interface SessionBuffer {
@@ -116,6 +119,7 @@ export class StorageCoordinator
   readonly policy: ResolvedStoragePolicy;
 
   private readonly definition: StorageDefinition;
+  private readonly keys: StorageKeys;
   private readonly agentName: string;
   private readonly projectRoot: string;
   private readonly logger: (line: string) => void;
@@ -137,6 +141,7 @@ export class StorageCoordinator
 
   constructor(options: StorageCoordinatorOptions) {
     this.definition = options.definition;
+    this.keys = options.keys ?? storageKeys;
     this.policy = resolveStoragePolicy(options.definition.policy);
     this.agentName = options.agentName;
     this.projectRoot = options.projectRoot;
@@ -215,7 +220,7 @@ export class StorageCoordinator
     if (first !== undefined) {
       ops.push(
         this.putOp(
-          storageKeys.sessionEvents(this.agentName, sessionId, first.index),
+          this.keys.sessionEvents(this.agentName, sessionId, first.index),
           buffer.events as unknown as JsonValue
         )
       );
@@ -223,7 +228,7 @@ export class StorageCoordinator
     if (buffer.record !== undefined) {
       ops.push(
         this.putOp(
-          storageKeys.session(this.agentName, sessionId),
+          this.keys.session(this.agentName, sessionId),
           buffer.record as unknown as JsonValue
         )
       );
@@ -249,14 +254,14 @@ export class StorageCoordinator
     if (previous != null) {
       ops.push(
         this.deleteOp(
-          storageKeys.continuation(this.agentName, record.channelId, previous)
+          this.keys.continuation(this.agentName, record.channelId, previous)
         )
       );
     }
     if (next != null) {
       ops.push(
         this.putOp(
-          storageKeys.continuation(this.agentName, record.channelId, next),
+          this.keys.continuation(this.agentName, record.channelId, next),
           { sessionId: record.sessionId }
         )
       );
@@ -303,9 +308,7 @@ export class StorageCoordinator
    * serve start.
    */
   async listSessions(): Promise<SessionRecord[]> {
-    const entries = await this.tryList(
-      storageKeys.sessionPrefix(this.agentName)
-    );
+    const entries = await this.tryList(this.keys.sessionPrefix(this.agentName));
     return entries
       .map((entry) => entry.value as unknown as SessionRecord)
       .filter((record) => record != null);
@@ -322,7 +325,7 @@ export class StorageCoordinator
       throw new Error("storage sink has no list");
     }
     const entries = await list(
-      storageKeys.sessionPrefix(this.agentName),
+      this.keys.sessionPrefix(this.agentName),
       this.context("restore")
     );
     if (!Array.isArray(entries)) {
@@ -345,7 +348,7 @@ export class StorageCoordinator
       return undefined;
     }
     const entries = await listNewest(
-      storageKeys.sessionPrefix(this.agentName),
+      this.keys.sessionPrefix(this.agentName),
       limit,
       this.context("restore")
     );
@@ -362,7 +365,7 @@ export class StorageCoordinator
    */
   async listSessionEvents(sessionId: string): Promise<SessionEvent[]> {
     const entries = await this.tryList(
-      storageKeys.sessionEventsPrefix(this.agentName, sessionId)
+      this.keys.sessionEventsPrefix(this.agentName, sessionId)
     );
     const events: SessionEvent[] = [];
     for (const entry of entries) {
@@ -389,7 +392,7 @@ export class StorageCoordinator
     }
     const ctx = this.context("restore");
     const record = (await get(
-      storageKeys.session(this.agentName, sessionId),
+      this.keys.session(this.agentName, sessionId),
       ctx
     )) as SessionRecord | null | undefined;
     if (record == null) {
@@ -422,7 +425,7 @@ export class StorageCoordinator
     }
     const ctx = this.context("restore");
     const pointer = await get(
-      storageKeys.continuation(this.agentName, channelId, continuationKey),
+      this.keys.continuation(this.agentName, channelId, continuationKey),
       ctx
     );
     if (pointer == null) {
@@ -482,7 +485,7 @@ export class StorageCoordinator
     if (get === undefined) {
       throw new Error("storage get is not configured");
     }
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     // Preserve stored JSON `null` (distinct from a missing key).
     return await get(key, this.context("restore"));
   }
@@ -492,13 +495,13 @@ export class StorageCoordinator
    * at-most-once delivery queue) so callers observe durable success/failure.
    */
   async kvPut(authorKey: string, value: JsonValue): Promise<void> {
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     await this.definition.put(key, value, this.context("policy"));
   }
 
   /** Awaited author KV delete. No-op when the sink omits `delete`. */
   async kvDelete(authorKey: string): Promise<void> {
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     await this.definition.delete?.(key, this.context("policy"));
   }
 

package/src/internal/store-mirror.ts

@@ -0,0 +1,86 @@
+/**
+ * Mirror an authored file tree onto an Agent Store prefix. Shared by the
+ * skills and workspace seed syncs so both keep the same write-then-sweep
+ * discipline and the same path refusals.
+ */
+
+import { posix } from "node:path";
+import { FileConflictError, type FileSink } from "../files.js";
+
+/**
+ * Write every `desired` key, then delete keys under `prefix` (and the
+ * `legacyPrefixes`) that nothing claims, so a redeploy drops removed files.
+ * Writes land before stale deletes, so a failed sync never leaves a gap a
+ * concurrent cloud reader could see.
+ */
+export async function mirrorToStore(args: {
+  sink: FileSink;
+  prefix: string;
+  desired: ReadonlyMap<string, Uint8Array>;
+  /** Pre-native layouts emptied on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
+  legacyPrefixes?: readonly string[];
+}): Promise<void> {
+  await Promise.all(
+    [...args.desired].map(([key, body]) =>
+      putLastWriterWins(args.sink, key, body)
+    )
+  );
+  const listed = await Promise.all(
+    [args.prefix, ...(args.legacyPrefixes ?? [])].map((prefix) =>
+      args.sink.list(prefix)
+    )
+  );
+  await Promise.all(
+    listed
+      .flat()
+      .filter((entry) => !args.desired.has(entry.key))
+      .map((entry) => args.sink.delete(entry.key))
+  );
+}
+
+/**
+ * Same refusals as local materialization's `resolveInside`: a rel that
+ * escapes its 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.
+ */
+export function storeRelPath(
+  relPath: string,
+  what: "skill file" | "workspace file"
+): 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 ${what} 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);
+  }
+}

package/src/internal/tenant-slack/relay.ts

@@ -0,0 +1,179 @@
+/**
+ * Relay-backed Slack posting for managed deployments.
+ *
+ * On AgentSDK v2 managed deployments the fork never receives a Slack token.
+ * The delivery envelope carries the matched automation's configured Slack
+ * **channel ids** only (`managedAutomation.slackChannels`, absent when the
+ * customer toggled "Send to Slack" off); each post goes through the control
+ * plane's Slack relay
+ * (`/internal/agent-serve/agent-sdk-slack-relay/:automationUuid`),
+ * authenticated with the pod's own `CURSOR_API_KEY`. The relay re-checks
+ * that the channel is configured on exactly that automation, renders the
+ * markdown, and posts as the Cursor Slack app with the customer's stored
+ * workspace token.
+ *
+ * INTERNAL: first-party multi-tenant deployment plumbing. Deliberately
+ * excluded from the published `@cursor/july` npm package (see the `files`
+ * whitelist); consumed by internal deployments via relative source imports.
+ */
+
+import {
+  cursorExternalApiUrl,
+  resolveApiKeySync,
+} from "../cursor/credentials.js";
+
+/**
+ * Path prefix of the backend relay route. Must match the mount in
+ * `backend/server/src/agentServe/agentServeEndpoints.ts`
+ * (`agentSdkSlackRelayRoutes`).
+ */
+export const AGENT_SDK_SLACK_RELAY_PATH_PREFIX =
+  "/internal/agent-serve/agent-sdk-slack-relay";
+
+/** Mirrors the relay's body bound; longer summaries are truncated client-side. */
+export const AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS = 12_000;
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Relay URL scoped to the source managed automation the delivery envelope
+ * attributed, so the relay checks the destination against exactly that
+ * automation's configured channels.
+ */
+export function relaySlackPostUrl(args: {
+  baseUrl: string;
+  automationUuid: string;
+}): string {
+  const trimmed = args.baseUrl.endsWith("/")
+    ? args.baseUrl.slice(0, -1)
+    : args.baseUrl;
+  return `${trimmed}${AGENT_SDK_SLACK_RELAY_PATH_PREFIX}/${encodeURIComponent(args.automationUuid)}`;
+}
+
+export type RelaySlackPostResult =
+  | { ok: true; channel: string; ts?: string; permalink?: string }
+  | {
+      ok: false;
+      channel: string;
+      /** HTTP status from the relay, or 0 when the request never completed. */
+      status: number;
+      error: string;
+    };
+
+export interface RelaySlackPostTarget {
+  relayBaseUrl: string;
+  apiKey: string;
+}
+
+/** Pod credential + external API base URL, or undefined off-platform. */
+export function resolveRelaySlackTarget(): RelaySlackPostTarget | undefined {
+  const resolved = resolveApiKeySync();
+  if (resolved === undefined) {
+    return undefined;
+  }
+  return { relayBaseUrl: cursorExternalApiUrl(), apiKey: resolved.apiKey };
+}
+
+function truncateMessage(message: string): string {
+  if (message.length <= AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS) {
+    return message;
+  }
+  const marker = "\n\n_(truncated)_";
+  return `${message.slice(0, AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS - marker.length)}${marker}`;
+}
+
+function describeError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.name === "TimeoutError" || error.name === "AbortError"
+      ? "relay request timed out"
+      : error.message;
+  }
+  return String(error);
+}
+
+/**
+ * Post one markdown message to one configured channel through the relay.
+ * Never throws: every failure is a `{ ok: false }` result so product code
+ * can log and continue (a Slack outage must not fail the review).
+ */
+export async function postRelaySlackMessage(args: {
+  /** Source managed automation uuid from the delivery envelope. */
+  automationUuid: string;
+  /** Configured channel id (from `managedAutomation.slackChannels`). */
+  channel: string;
+  /** Markdown body. */
+  message: string;
+  /** Parent message ts to reply in a thread. */
+  threadTs?: string;
+  /** Test seam; defaults to the pod credential + external API base URL. */
+  resolve?: () => RelaySlackPostTarget | undefined;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}): Promise<RelaySlackPostResult> {
+  const channel = args.channel.trim();
+  if (channel === "") {
+    return { ok: false, channel, status: 0, error: "empty channel" };
+  }
+  const target = (args.resolve ?? resolveRelaySlackTarget)();
+  if (target === undefined) {
+    return {
+      ok: false,
+      channel,
+      status: 0,
+      error: "no Cursor credential for the Slack relay",
+    };
+  }
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const url = relaySlackPostUrl({
+    baseUrl: target.relayBaseUrl,
+    automationUuid: args.automationUuid,
+  });
+  let response: Response;
+  try {
+    response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${target.apiKey}`,
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      body: JSON.stringify({
+        channel,
+        message: truncateMessage(args.message),
+        ...(args.threadTs === undefined ? {} : { threadTs: args.threadTs }),
+      }),
+      signal: AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (error) {
+    return { ok: false, channel, status: 0, error: describeError(error) };
+  }
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    body = undefined;
+  }
+  const record =
+    typeof body === "object" && body !== null && !Array.isArray(body)
+      ? (body as Record<string, unknown>)
+      : {};
+  if (!response.ok || record.ok !== true) {
+    return {
+      ok: false,
+      channel,
+      status: response.status,
+      error:
+        typeof record.error === "string" && record.error !== ""
+          ? record.error
+          : `relay responded ${response.status}`,
+    };
+  }
+  return {
+    ok: true,
+    channel: typeof record.channel === "string" ? record.channel : channel,
+    ...(typeof record.ts === "string" ? { ts: record.ts } : {}),
+    ...(typeof record.permalink === "string"
+      ? { permalink: record.permalink }
+      : {}),
+  };
+}