@cursor/july 0.1.39 → 0.1.41

package/src/internal/cli-deploy.ts

@@ -117,6 +117,12 @@ export interface DeployCliOptions {
   err?: (text: string) => void;
   /** `secrets set` value input (hidden prompt on a TTY, lines otherwise). */
   stdin?: SecretInputStream;
+  /**
+   * Opt in to `NAME=VALUE` argv secrets. Default is names only (hidden
+   * prompt / stdin) so values never land in shell history or agent-captured
+   * terminals.
+   */
+  fromArgv?: boolean;
 }
 
 /** Minimal stdin surface `secrets set` reads values from (test-injectable). */
@@ -1143,8 +1149,9 @@ export async function cmdSecretsSet(
   const usageErr = options.err ?? ((t: string) => void process.stderr.write(t));
   if (slug === undefined || slug === "" || specs.length === 0) {
     usageErr(
-      `Usage: ${CLI} secrets set <slug> NAME[=VALUE] [NAME2[=VALUE2] ...] [--team <id>] [--json]\n` +
-        `NAMEs without =VALUE are prompted for (hidden input; reads stdin when piped).\n`
+      `Usage: ${CLI} secrets set <slug> NAME [NAME2 ...] [--team <id>] [--json]\n` +
+        `  Enter values at the hidden prompt, or pipe one line per NAME.\n` +
+        `  Opt-in (leaks into argv / agent terminals): NAME=VALUE … --from-argv\n`
     );
     return 1;
   }
@@ -1162,9 +1169,20 @@ export async function cmdSecretsSet(
     }
     parsed.push(eq === -1 ? { name } : { name, value: spec.slice(eq + 1) });
   }
-  if (parsed.some((entry) => entry.value !== undefined)) {
+  const hasArgvValues = parsed.some((entry) => entry.value !== undefined);
+  if (hasArgvValues && options.fromArgv !== true) {
+    usageErr(
+      `Refusing NAME=VALUE on argv (shows up in shell history and agent-captured terminals).\n` +
+        `Pass names only:\n` +
+        `  ${CLI} secrets set ${slug} NAME\n` +
+        `Hidden prompt on a TTY; one stdin line per NAME when piped.\n` +
+        `Or redirect a file: ${CLI} secrets set ${slug} NAME < ./secret.txt\n`
+    );
+    return 1;
+  }
+  if (hasArgvValues) {
     usageErr(
-      `warning: secret values passed as arguments can end up in shell history; prefer \`${CLI} secrets set ${slug} NAME\` and enter the value at the hidden prompt.\n`
+      `warning: --from-argv puts secret values in argv (shell history and agent-captured terminals).\n`
     );
   }
 

package/src/internal/cli-mcp-oauth.ts

@@ -209,7 +209,9 @@ export async function authorizeHostMcpOauth(
 
     let callback: Awaited<ReturnType<typeof waitForMcpOAuthCallback>>;
     try {
-      callback = await waitForMcpOAuthCallback();
+      callback = await waitForMcpOAuthCallback({
+        authorizationUrl: redirect.toString(),
+      });
     } catch (error) {
       err(`${LOG_PREFIX} OAuth callback failed: ${describe(error)}\n`);
       return { ok: false };

package/src/internal/cli-mcp.ts

@@ -654,15 +654,15 @@ async function cmdMcpInstallRemote(options: McpCliOptions): Promise<number> {
   }
 
   // Verify the deployment resolves before writing config that cannot work.
-  // This read is admin-tier, but calling the gateway only needs team
-  // membership — so a 403 means "cannot verify", not "cannot use": warn and
-  // still write the entry rather than locking members out of their own agent.
+  // A 403 here is team membership or cloud-agent entitlement, not an
+  // admin-tier read. Still write the entry: calling the gateway only
+  // needs the API key.
   try {
     await auth.client.getDeployment({ teamId: auth.teamId, slug });
   } catch (error) {
     if (error instanceof DeployApiError && error.status === 403) {
       err(
-        `Could not verify deployment "${slug}" (reading deployments needs team-admin); writing the entry anyway.\n`
+        `Could not verify deployment "${slug}" (not authorized for this team); writing the entry anyway.\n`
       );
     } else {
       err(`${describeError(error)}\n`);

package/src/internal/cursor-event-relay.ts

@@ -57,6 +57,40 @@ export type CursorScmPullRequestMeta = {
   baseSha?: string;
 };
 
+/** PR ref on a Checks / Actions webhook object. */
+export type CursorScmCiPullRequestMeta = {
+  number: number;
+  url?: string;
+};
+
+export type CursorScmCiAppMeta = {
+  slug?: string;
+  name?: string;
+};
+
+/** Shared Checks / Actions fields. `id` + `headSha` satisfy the channel Zod schemas. */
+type CursorScmCiBaseMeta = {
+  id: number;
+  headSha: string;
+  status?: string;
+  conclusion?: string | null;
+  htmlUrl?: string;
+  app?: CursorScmCiAppMeta;
+  pullRequests: CursorScmCiPullRequestMeta[];
+};
+
+export type CursorScmCheckRunMeta = CursorScmCiBaseMeta & {
+  name?: string;
+  checkSuiteId?: number;
+};
+
+export type CursorScmCheckSuiteMeta = CursorScmCiBaseMeta;
+
+export type CursorScmWorkflowRunMeta = CursorScmCiBaseMeta & {
+  name?: string;
+  workflowId?: number;
+};
+
 /** One event delivered by `GET /v0/scm-events` (metadata only). */
 export interface CursorScmEvent {
   offset: string;
@@ -81,6 +115,12 @@ export interface CursorScmEvent {
    * Zod-valid `issue_comment` / `pull_request_review_comment` webhook body.
    */
   comment?: CursorScmCommentMeta;
+  /** `check_run` snapshot; enough to stub `onCheckRun`. */
+  checkRun?: CursorScmCheckRunMeta;
+  /** `check_suite` snapshot; enough to stub `onCheckSuite`. */
+  checkSuite?: CursorScmCheckSuiteMeta;
+  /** `workflow_run` snapshot; enough to stub `onWorkflowRun`. */
+  workflowRun?: CursorScmWorkflowRunMeta;
   /** GitHub-side event time from the payload, when present. */
   occurredAtMs?: number;
 }
@@ -138,12 +178,37 @@ export function formatCursorScmEventLog(event: {
   return `${event.eventName}${action} on ${pr} received=${received}${occurred} (${delivery})`;
 }
 
+/** Relay log suffix for one fan-out target, including parse errors on 4xx. */
+export function formatCursorScmDispatchOutcome(target: {
+  slug: string;
+  status: number;
+  body: unknown;
+}): string {
+  const slug = target.slug === "" ? "default" : target.slug;
+  if (target.status < 400) {
+    return `${slug}:${target.status}`;
+  }
+  const error = readDispatchError(target.body);
+  return error === undefined
+    ? `${slug}:${target.status}`
+    : `${slug}:${target.status} ${error}`;
+}
+
+function readDispatchError(body: unknown): string | undefined {
+  if (typeof body !== "object" || body === null) return undefined;
+  if (!("error" in body)) return undefined;
+  const error = body.error;
+  return typeof error === "string" && error !== "" ? error : undefined;
+}
+
 /**
  * Minimal GitHub webhook body from an SCM-events metadata envelope.
  * When `pullRequest` has title + head/base refs+shas, emits a Zod-valid
  * `pull_request` object for `onPullRequest`; otherwise identity-only stubs.
  * When `comment` is present, emits a Zod-valid `comment` object so relayed
  * `issue_comment` / `pull_request_review_comment` deliveries dispatch.
+ * When a CI snapshot is present, emits `check_run` / `check_suite` /
+ * `workflow_run` so those typed hooks parse on the `--cursor-events` path.
  */
 export function scmMetadataToGitHubPayload(event: {
   repo: string;
@@ -152,6 +217,9 @@ export function scmMetadataToGitHubPayload(event: {
   prUrl?: string;
   pullRequest?: CursorScmPullRequestMeta;
   comment?: CursorScmCommentMeta;
+  checkRun?: CursorScmCheckRunMeta;
+  checkSuite?: CursorScmCheckSuiteMeta;
+  workflowRun?: CursorScmWorkflowRunMeta;
 }): Record<string, unknown> {
   const slash = event.repo.indexOf("/");
   const owner = slash === -1 ? "" : event.repo.slice(0, slash);
@@ -210,6 +278,30 @@ export function scmMetadataToGitHubPayload(event: {
     payload.comment = comment;
   }
 
+  const checkPullRequests = stubGitHubCiPullRequests({
+    snapshot:
+      event.checkRun?.pullRequests ??
+      event.checkSuite?.pullRequests ??
+      event.workflowRun?.pullRequests,
+    prNumber,
+    prUrl,
+  });
+  if (event.checkRun !== undefined) {
+    payload.check_run = stubGitHubCheckRun(event.checkRun, checkPullRequests);
+  }
+  if (event.checkSuite !== undefined) {
+    payload.check_suite = stubGitHubCheckSuite(
+      event.checkSuite,
+      checkPullRequests
+    );
+  }
+  if (event.workflowRun !== undefined) {
+    payload.workflow_run = stubGitHubWorkflowRun(
+      event.workflowRun,
+      checkPullRequests
+    );
+  }
+
   const title = prMeta?.title;
   const headRef = prMeta?.headRef;
   const headSha = prMeta?.headSha;
@@ -261,6 +353,82 @@ export function scmMetadataToGitHubPayload(event: {
   return payload;
 }
 
+function stubGitHubCiPullRequests(input: {
+  snapshot: CursorScmCiPullRequestMeta[] | undefined;
+  prNumber: number | undefined;
+  prUrl: string | undefined;
+}): Array<{ number: number; html_url?: string }> {
+  if (input.snapshot !== undefined && input.snapshot.length > 0) {
+    return input.snapshot.map((pr) => ({
+      number: pr.number,
+      ...(pr.url === undefined ? {} : { html_url: pr.url }),
+    }));
+  }
+  if (input.prNumber === undefined) return [];
+  return [
+    {
+      number: input.prNumber,
+      ...(input.prUrl === undefined ? {} : { html_url: input.prUrl }),
+    },
+  ];
+}
+
+function stubGitHubCiApp(
+  app: CursorScmCiAppMeta | undefined
+): Record<string, unknown> | undefined {
+  if (app === undefined) return undefined;
+  const out: Record<string, unknown> = {};
+  if (app.slug !== undefined) out.slug = app.slug;
+  if (app.name !== undefined) out.name = app.name;
+  return out;
+}
+
+function stubGitHubCiBase(
+  meta: CursorScmCiBaseMeta,
+  pullRequests: Array<{ number: number; html_url?: string }>
+): Record<string, unknown> {
+  const object: Record<string, unknown> = {
+    id: meta.id,
+    head_sha: meta.headSha,
+  };
+  if (meta.status !== undefined) object.status = meta.status;
+  if (meta.conclusion !== undefined) object.conclusion = meta.conclusion;
+  if (meta.htmlUrl !== undefined) object.html_url = meta.htmlUrl;
+  const app = stubGitHubCiApp(meta.app);
+  if (app !== undefined) object.app = app;
+  if (pullRequests.length > 0) object.pull_requests = pullRequests;
+  return object;
+}
+
+function stubGitHubCheckRun(
+  meta: CursorScmCheckRunMeta,
+  pullRequests: Array<{ number: number; html_url?: string }>
+): Record<string, unknown> {
+  const object = stubGitHubCiBase(meta, pullRequests);
+  if (meta.name !== undefined) object.name = meta.name;
+  if (meta.checkSuiteId !== undefined) {
+    object.check_suite = { id: meta.checkSuiteId };
+  }
+  return object;
+}
+
+function stubGitHubCheckSuite(
+  meta: CursorScmCheckSuiteMeta,
+  pullRequests: Array<{ number: number; html_url?: string }>
+): Record<string, unknown> {
+  return stubGitHubCiBase(meta, pullRequests);
+}
+
+function stubGitHubWorkflowRun(
+  meta: CursorScmWorkflowRunMeta,
+  pullRequests: Array<{ number: number; html_url?: string }>
+): Record<string, unknown> {
+  const object = stubGitHubCiBase(meta, pullRequests);
+  if (meta.name !== undefined) object.name = meta.name;
+  if (meta.workflowId !== undefined) object.workflow_id = meta.workflowId;
+  return object;
+}
+
 /**
  * GitHub SCM-events relay: a thin {@link CursorRelayCore} adapter. Consumers
  * keep the same `new CursorEventRelay(options).start()/.stop()` surface.

package/src/internal/deploy-client.ts

@@ -705,7 +705,7 @@ function mapErrorResponse(
       );
     case 403:
       return new DeployApiError(
-        `${serverError ?? "Not authorized"} — deploying needs team-admin permission and the cloud-agent entitlement on that team.`,
+        `${serverError ?? "Not authorized"} — deploying needs team membership and the cloud-agent entitlement on that team.`,
         403
       );
     case 404: {

package/src/internal/discovery.ts

@@ -28,6 +28,7 @@ import {
   type AgentProject,
   type AgentProjectInfo,
   type AgentRuntime,
+  type AgentServingMode,
   type ArtifactsDefinition,
   type BuiltinToolsConfig,
   type ChannelDefinition,
@@ -188,11 +189,20 @@ export async function loadAgentProjects(
     );
   }
   const results: Array<{ slug: string; project: AgentProject }> = [];
+  // Storage namespaces (session mirror, host kv, durable-session ledger)
+  // key on the project NAME, not the mount slug — two co-hosted agents
+  // sharing a name would silently share sessions and coordination state.
+  const slugByName = new Map<string, string>();
   for (const child of children) {
-    results.push({
-      slug: child.slug,
-      project: await loadAgentProject(child.dir, options),
-    });
+    const project = await loadAgentProject(child.dir, options);
+    const priorSlug = slugByName.get(project.name);
+    if (priorSlug !== undefined) {
+      throw new Error(
+        `Duplicate agent name "${project.name}" under ${resolved}: agents "${priorSlug}" and "${child.slug}" both resolve to it (package.json "name", or the directory name when unset). Co-hosted agents must have distinct names — their storage and session namespaces key on the name.`
+      );
+    }
+    slugByName.set(project.name, child.slug);
+    results.push({ slug: child.slug, project });
   }
   return results;
 }
@@ -420,6 +430,7 @@ async function loadAgent(
         };
   const hosting = resolveHosting(ctx, agentDir, config?.hosting);
   const concurrency = resolveConcurrency(ctx, agentDir, config?.concurrency);
+  const serving = resolveServing(ctx, agentDir, config?.serving);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -443,6 +454,7 @@ async function loadAgent(
     local,
     hosting,
     concurrency,
+    serving,
     tools,
     skills,
     connections,
@@ -451,6 +463,27 @@ async function loadAgent(
   };
 }
 
+/**
+ * Validate the authored serving mode. An unrecognized value is an error
+ * diagnostic and falls back to undefined (resident) — a typo must not
+ * silently opt an agent into (or out of) ledger coordination.
+ */
+function resolveServing(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  serving: AgentServingMode | undefined
+): AgentServingMode | undefined {
+  if (serving === undefined || serving === "resident" || serving === "ledger") {
+    return serving;
+  }
+  ctx.diagnostics.push({
+    severity: "error",
+    path: displayPath(ctx, join(agentDir, "agent.ts")),
+    message: `serving must be "resident" or "ledger"; got ${JSON.stringify(serving)}.`,
+  });
+  return undefined;
+}
+
 /** Absolute harness cwd parent, or undefined when unset / blank. */
 function resolveAgentCwd(
   ctx: DiscoveryContext,
@@ -504,7 +537,7 @@ function resolveHosting(
       warn(`hosting.secretNames: ${nameError}`);
     } else if (isReservedSecretName(name)) {
       warn(
-        `hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / Cursor-hosted storage) and injected automatically; omit it from secretNames.`
+        `hosting.secretNames: ${JSON.stringify(name)} is platform-managed (CURSOR_* / reserved hosted-storage names); omit it from secretNames.`
       );
     }
   }
@@ -1863,6 +1896,10 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       name: connection.name,
       transport: connectionTransportLabel(connection.transport),
       hostOnly: connection.hostOnly,
+      cursorAccountServers:
+        "cursorAccount" in connection.transport
+          ? (connection.transport.servers ?? "*")
+          : undefined,
     })),
     subagents: agent.subagents.map((subagent) => ({
       name: subagent.name,

package/src/internal/distribution.ts

@@ -108,8 +108,10 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["evals/loaders", "evals/loaders.js"],
   ["ab", "ab.js"],
   ["artifacts", "artifacts.js"],
+  ["kv", "kv.js"],
+  ["kv/memory", "kv/memory-kv.js"],
+  ["ledger", "ledger.js"],
   ["storage", "storage.js"],
   ["storage/file-kv", "storage-backends/file-kv.js"],
-  ["storage/postgres-kv", "storage-backends/postgres-kv.js"],
   ["storage/cursor-hosted", "storage-backends/cursor-hosted.js"],
 ];

package/src/internal/durable-session-store.ts

@@ -0,0 +1,95 @@
+/**
+ * Durable-session store resolution.
+ *
+ * Two APIs, one backend: `defineStorage` is the **storage API** (agent
+ * state — session records, event chunks, author KV), and the session
+ * ledger is the **durable session API** (session identity, leases,
+ * fenced commits). The ledger consumes {@link SessionLedgerKv} — exactly
+ * the three CAS methods it uses, nothing more; this module adapts a
+ * storage backend's `cas` group into that interface, so a deployment's
+ * one authored backend serves both APIs by default.
+ *
+ * Calls go straight at the config's methods — NOT through the
+ * StorageCoordinator: the coordinator's queue is bounded, serialized, and
+ * at-most-once (mirror semantics), while ledger CAS calls are the
+ * correctness path and must observe their own results synchronously.
+ */
+
+import type { SessionLedgerKv } from "../ledger/session-ledger.js";
+import {
+  keySegment,
+  STORAGE_KEY_ROOT,
+  type StorageConfig,
+  type StorageContext,
+} from "../storage.js";
+
+export interface StorageCasKvArgs {
+  agentName: string;
+  projectRoot: string;
+}
+
+/**
+ * Adapt a storage backend's `cas` group into the ledger's KV interface.
+ * Throws when the backend does not implement `cas` — the caller turns
+ * that into the fail-fast startup error for `serving: "ledger"`. Every
+ * call carries a `reason: "coordination"` {@link StorageContext}.
+ */
+export function storageCasKv(
+  config: StorageConfig,
+  args: StorageCasKvArgs
+): SessionLedgerKv {
+  const ctx: StorageContext = {
+    agentName: args.agentName,
+    projectRoot: args.projectRoot,
+    reason: "coordination",
+  };
+  const { cas } = config;
+  if (cas === undefined) {
+    throw new Error(
+      "storageCasKv: the storage backend does not implement the cas group (conditional writes)"
+    );
+  }
+  return {
+    async getWithVersion(key) {
+      return await cas.getWithVersion(key, ctx);
+    },
+    async putIfAbsent(key, value) {
+      return await cas.putIfAbsent(key, value, ctx);
+    },
+    async putIfVersion(key, value, expectedVersion) {
+      return await cas.putIfVersion(key, value, expectedVersion, ctx);
+    },
+  };
+}
+
+/**
+ * The one place the ledger's physical namespace is minted:
+ * `agentkit/v1/<agent>/durable-session/` — the {@link STORAGE_KEY_ROOT}
+ * conventions with the agent segment encoded like every other
+ * caller-controlled segment. The ledger itself never sees this string;
+ * it speaks bare `session/…` / `ledger/…` keys against a handle that
+ * {@link namespacedKv} has already scoped.
+ */
+export function ledgerKeyPrefix(agentName: string): string {
+  return `${STORAGE_KEY_ROOT}/${keySegment(agentName)}/durable-session/`;
+}
+
+/**
+ * Scope a raw store handle under a namespace, prepending it to every
+ * key on the way in. Applied exactly once, where the engine constructs
+ * the ledger's store handle — the same conceptual boundary where
+ * `host.kv` gets its agent scoping. Internal: not part of the public kv
+ * interface, and callers (including the explicit `durableSessionStore`
+ * override) always supply the raw store — they never write prefixes.
+ */
+export function namespacedKv(
+  store: SessionLedgerKv,
+  namespace: string
+): SessionLedgerKv {
+  return {
+    getWithVersion: (key) => store.getWithVersion(namespace + key),
+    putIfAbsent: (key, value) => store.putIfAbsent(namespace + key, value),
+    putIfVersion: (key, value, expectedVersion) =>
+      store.putIfVersion(namespace + key, value, expectedVersion),
+  };
+}

package/src/internal/hosting.ts

@@ -15,7 +15,7 @@ export const MAX_SECRETS = 32;
 export const MAX_SECRET_VALUE_BYTES = 4096;
 /** Max secret name length. */
 export const MAX_SECRET_NAME_LENGTH = 64;
-/** Secret names the platform injects; user writes are rejected. */
+/** Secret names the platform manages; user writes are rejected. */
 export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
 
 /**
@@ -84,7 +84,7 @@ export function validateSettableSecretName(name: string): string | undefined {
     return nameError;
   }
   if (isReservedSecretName(name)) {
-    return `Secret name ${JSON.stringify(name)} is platform-managed; the platform injects CURSOR_* and Cursor-hosted storage values automatically.`;
+    return `Secret name ${JSON.stringify(name)} is platform-managed; user secrets cannot claim CURSOR_* or reserved hosted-storage names.`;
   }
   return undefined;
 }