@cursor/july 0.1.102 → 0.1.104

package/src/internal/session-run-log.ts

@@ -26,6 +26,7 @@ import type { AgentProject } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { describeError } from "./describe-error.js";
 import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
+import { isRecord } from "./is-record.js";
 import type { LogRingEntry } from "./log-ring.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
@@ -193,10 +194,6 @@ export function snapshotSessionRunLogs(
   }));
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function decodeSinkBody(body: Uint8Array | { body: Uint8Array }): Uint8Array {
   return body instanceof Uint8Array ? body : body.body;
 }

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/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 }
+      : {}),
+  };
+}

package/src/internal/testing/factory-resource-fixtures.ts

@@ -0,0 +1,85 @@
+/**
+ * Factory resource continuation fixtures shared by July and the control
+ * plane identity suite. Pure data: no imports, so server-shared can load
+ * this file by relative path without pulling `@cursor/july`.
+ */
+
+export const FACTORY_CHECKPOINT_NAME: string =
+  "changeMonitors/cm-1/checkpoints/cp-1";
+export const FACTORY_ISSUE_NAME: string = "issues/iss-1";
+
+export interface FactoryCheckpointResourceFixture {
+  name: string;
+  deployment: string;
+  runKey: string;
+  issues: { title: string };
+  evidenceSummary: string;
+  planRevision: string;
+  createTime: string;
+  description: string;
+}
+
+export interface FactoryIssueResourceFixture {
+  name: string;
+  title: string;
+  body: string;
+  state: "STATE_OPEN";
+  createTime: string;
+  updateTime: string;
+  path: string;
+  etag: string;
+}
+
+export interface CheckpointCreatedPayloadFixture {
+  eventId: string;
+  eventType: "checkpoint.created";
+  teamId: string;
+  occurredAtMs: number;
+  checkpoint: FactoryCheckpointResourceFixture;
+}
+
+export interface IssueCreatedPayloadFixture {
+  eventId: string;
+  eventType: "issue.created";
+  teamId: string;
+  occurredAtMs: number;
+  issue: FactoryIssueResourceFixture;
+}
+
+export const FACTORY_CHECKPOINT_RESOURCE: FactoryCheckpointResourceFixture = {
+  name: FACTORY_CHECKPOINT_NAME,
+  deployment: "deployments/11111111-1111-4111-8111-111111111111",
+  runKey: "t+1h",
+  issues: { title: "POST /checkout 500 rate elevated" },
+  evidenceSummary: "5xx rate rose after the deploy.",
+  planRevision: "changeMonitors/cm-1/planRevisions/3",
+  createTime: "2026-09-08T21:00:00Z",
+  description: "Checkout 500s are elevated.",
+};
+
+export const FACTORY_ISSUE_RESOURCE: FactoryIssueResourceFixture = {
+  name: FACTORY_ISSUE_NAME,
+  title: "Checkout 500s",
+  body: "5xx rate rose after the deploy.",
+  state: "STATE_OPEN",
+  createTime: "2026-09-08T21:00:00Z",
+  updateTime: "2026-09-08T21:00:00Z",
+  path: "checkout/500s",
+  etag: 'W/"1"',
+};
+
+export const CHECKPOINT_CREATED_PAYLOAD: CheckpointCreatedPayloadFixture = {
+  eventId: "evt-cp-1",
+  eventType: "checkpoint.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  checkpoint: FACTORY_CHECKPOINT_RESOURCE,
+};
+
+export const ISSUE_CREATED_PAYLOAD: IssueCreatedPayloadFixture = {
+  eventId: "evt-iss-1",
+  eventType: "issue.created",
+  teamId: "team-1",
+  occurredAtMs: 1,
+  issue: FACTORY_ISSUE_RESOURCE,
+};