@cursor/july 0.1.47 → 0.1.49

package/src/internal/process-memory-telemetry.ts

@@ -0,0 +1,373 @@
+/**
+ * Process heap + event-log residency for hosted engines.
+ *
+ * Pod RSS (`runner_daemon.pod.memory_usage_bytes`) cannot show a V8 heap-cap
+ * OOM: the cgroup limit is tens of GB while Node aborts near
+ * `--max-old-space-size`. The live path is `/v1/health`: the control plane
+ * already probes every engine and emits `cursor.agent_serve.engine.*` gauges.
+ * An optional in-process sampler (`AGENT_SDK_MEMORY_METRICS=1`) still logs
+ * and, if a Datadog key happens to be in the pod, posts directly.
+ *
+ * `event_log.events_retained` is the in-process cache size (the OOM
+ * suspect). `event_log.events_total` is the durable recorded count. They
+ * are equal today; a later consume-and-drop change should split them.
+ */
+
+import { getHeapStatistics } from "node:v8";
+import type { Attributes, Meter } from "@opentelemetry/api";
+import type { EventLogMemoryStats } from "./event-log.js";
+
+const DEFAULT_INTERVAL_MS = 15_000;
+const DEFAULT_DD_SITE = "us5.datadoghq.com";
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MB = 1024 * 1024;
+
+export const MEMORY_METRIC_PREFIX = "agent_sdk.memory";
+export const EVENT_LOG_METRIC_PREFIX = "agent_sdk.event_log";
+
+export type ProcessMemorySample = {
+  heapUsedBytes: number;
+  heapTotalBytes: number;
+  heapLimitBytes: number;
+  rssBytes: number;
+  externalBytes: number;
+};
+
+export type DatadogMemoryMetricsConfig = {
+  apiKey: string;
+  seriesUrl: string;
+  timeoutMs: number;
+};
+
+export type ProcessMemoryTelemetryOptions = {
+  agentName: string;
+  getEventLogStats: () => EventLogMemoryStats;
+  logger?: (line: string) => void;
+  meter?: Meter;
+  env?: NodeJS.ProcessEnv;
+  intervalMs?: number;
+  now?: () => number;
+  memoryUsage?: () => {
+    heapUsed: number;
+    heapTotal: number;
+    rss: number;
+    external: number;
+  };
+  heapSizeLimit?: () => number;
+  postSeries?: (
+    config: DatadogMemoryMetricsConfig,
+    body: string
+  ) => Promise<void>;
+};
+
+export function shouldStartProcessMemoryTelemetry(
+  env: NodeJS.ProcessEnv = process.env
+): boolean {
+  const flag = env.AGENT_SDK_MEMORY_METRICS?.trim().toLowerCase();
+  return flag === "1" || flag === "true";
+}
+
+export function resolveDatadogMemoryMetricsConfig(
+  env: NodeJS.ProcessEnv = process.env
+): DatadogMemoryMetricsConfig | undefined {
+  const apiKey = env.DATADOG_API_KEY?.trim() || env.DD_API_KEY?.trim();
+  if (apiKey === undefined || apiKey === "") {
+    return undefined;
+  }
+  const site = env.DD_SITE?.trim() || DEFAULT_DD_SITE;
+  return {
+    apiKey,
+    seriesUrl: `https://api.${site}/api/v1/series`,
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  };
+}
+
+export function sampleProcessMemory(
+  args: {
+    memoryUsage?: ProcessMemoryTelemetryOptions["memoryUsage"];
+    heapSizeLimit?: ProcessMemoryTelemetryOptions["heapSizeLimit"];
+  } = {}
+): ProcessMemorySample {
+  const usage = args.memoryUsage?.() ?? process.memoryUsage();
+  const heapLimitBytes =
+    args.heapSizeLimit?.() ?? getHeapStatistics().heap_size_limit;
+  return {
+    heapUsedBytes: usage.heapUsed,
+    heapTotalBytes: usage.heapTotal,
+    heapLimitBytes,
+    rssBytes: usage.rss,
+    externalBytes: usage.external,
+  };
+}
+
+export type MemoryHealthFields = {
+  memory: ProcessMemorySample & { heapUsedRatio: number };
+  eventLog: EventLogMemoryStats;
+};
+
+export function heapUsedRatio(memory: ProcessMemorySample): number {
+  return memory.heapLimitBytes > 0
+    ? memory.heapUsedBytes / memory.heapLimitBytes
+    : 0;
+}
+
+export function sumEventLogStats(
+  stats: readonly EventLogMemoryStats[]
+): EventLogMemoryStats {
+  let residentSessions = 0;
+  let eventsRetained = 0;
+  let eventsTotal = 0;
+  for (const item of stats) {
+    residentSessions += item.residentSessions;
+    eventsRetained += item.eventsRetained;
+    eventsTotal += item.eventsTotal;
+  }
+  return { residentSessions, eventsRetained, eventsTotal };
+}
+
+/** Fields attached to `/v1/health` so the control plane can scrape them. */
+export function buildMemoryHealthFields(
+  eventLog: EventLogMemoryStats,
+  sample: ProcessMemorySample = sampleProcessMemory()
+): MemoryHealthFields {
+  return {
+    memory: { ...sample, heapUsedRatio: heapUsedRatio(sample) },
+    eventLog,
+  };
+}
+
+/**
+ * Best-effort health payload. Sampling or event-log stats must never fail
+ * `/v1/health`; omit the fields instead.
+ */
+export function collectMemoryHealthFields(args: {
+  eventLog: () => EventLogMemoryStats;
+  sample?: () => ProcessMemorySample;
+}): MemoryHealthFields | Record<string, never> {
+  try {
+    return buildMemoryHealthFields(
+      args.eventLog(),
+      args.sample === undefined ? sampleProcessMemory() : args.sample()
+    );
+  } catch {
+    return {};
+  }
+}
+
+export function formatMemoryLogLine(args: {
+  agentName: string;
+  memory: ProcessMemorySample;
+  eventLog: EventLogMemoryStats;
+}): string {
+  const ratio = heapUsedRatio(args.memory);
+  return (
+    `[agent-sdk:memory] agent=${args.agentName}` +
+    ` heap_used_mb=${mb(args.memory.heapUsedBytes)}` +
+    ` heap_total_mb=${mb(args.memory.heapTotalBytes)}` +
+    ` heap_limit_mb=${mb(args.memory.heapLimitBytes)}` +
+    ` heap_used_ratio=${ratio.toFixed(3)}` +
+    ` rss_mb=${mb(args.memory.rssBytes)}` +
+    ` event_log.sessions=${args.eventLog.residentSessions}` +
+    ` event_log.retained=${args.eventLog.eventsRetained}` +
+    ` event_log.total=${args.eventLog.eventsTotal}`
+  );
+}
+
+export function buildDatadogGaugeSeries(args: {
+  agentName: string;
+  memory: ProcessMemorySample;
+  eventLog: EventLogMemoryStats;
+  timestampSec: number;
+}): Array<{
+  metric: string;
+  type: "gauge";
+  points: [[number, number]];
+  tags: string[];
+}> {
+  const tags = [`agent_sdk.agent:${sanitizeTag(args.agentName)}`];
+  const heapRatio = heapUsedRatio(args.memory);
+  const points: Array<{ name: string; value: number }> = [
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_used_bytes`,
+      value: args.memory.heapUsedBytes,
+    },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_total_bytes`,
+      value: args.memory.heapTotalBytes,
+    },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.heap_limit_bytes`,
+      value: args.memory.heapLimitBytes,
+    },
+    { name: `${MEMORY_METRIC_PREFIX}.rss_bytes`, value: args.memory.rssBytes },
+    {
+      name: `${MEMORY_METRIC_PREFIX}.external_bytes`,
+      value: args.memory.externalBytes,
+    },
+    { name: `${MEMORY_METRIC_PREFIX}.heap_used_ratio`, value: heapRatio },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`,
+      value: args.eventLog.residentSessions,
+    },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.events_retained`,
+      value: args.eventLog.eventsRetained,
+    },
+    {
+      name: `${EVENT_LOG_METRIC_PREFIX}.events_total`,
+      value: args.eventLog.eventsTotal,
+    },
+  ];
+  return points.map((point) => ({
+    metric: point.name,
+    type: "gauge",
+    points: [[args.timestampSec, point.value]],
+    tags,
+  }));
+}
+
+/** Start the sampler. Returns a stop function. */
+export function startProcessMemoryTelemetry(
+  options: ProcessMemoryTelemetryOptions
+): () => void {
+  const env = options.env ?? process.env;
+  const logger = options.logger ?? (() => {});
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const datadog = resolveDatadogMemoryMetricsConfig(env);
+  const attributes: Attributes = { "agent_sdk.agent": options.agentName };
+  let stopped = false;
+  let inFlight: Promise<void> | undefined;
+
+  const sample = (): void => {
+    if (stopped) {
+      return;
+    }
+    const memory = sampleProcessMemory({
+      memoryUsage: options.memoryUsage,
+      heapSizeLimit: options.heapSizeLimit,
+    });
+    const eventLog = options.getEventLogStats();
+    logger(
+      formatMemoryLogLine({ agentName: options.agentName, memory, eventLog })
+    );
+    recordOtel(options.meter, memory, eventLog, attributes);
+    if (datadog === undefined) {
+      return;
+    }
+    const body = JSON.stringify({
+      series: buildDatadogGaugeSeries({
+        agentName: options.agentName,
+        memory,
+        eventLog,
+        timestampSec: Math.floor((options.now?.() ?? Date.now()) / 1000),
+      }),
+    });
+    const post = options.postSeries ?? defaultPostSeries;
+    inFlight = post(datadog, body).catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      logger(`[agent-sdk:memory] datadog flush failed: ${message}`);
+    });
+  };
+
+  sample();
+  const timer = setInterval(sample, intervalMs);
+  timer.unref();
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+    void inFlight;
+  };
+}
+
+function recordOtel(
+  meter: Meter | undefined,
+  memory: ProcessMemorySample,
+  eventLog: EventLogMemoryStats,
+  attributes: Attributes
+): void {
+  if (meter === undefined) {
+    return;
+  }
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.heap_used_bytes`).record(
+    memory.heapUsedBytes,
+    attributes
+  );
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.heap_limit_bytes`).record(
+    memory.heapLimitBytes,
+    attributes
+  );
+  histogram(meter, `${MEMORY_METRIC_PREFIX}.rss_bytes`).record(
+    memory.rssBytes,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_retained`).record(
+    eventLog.eventsRetained,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.events_total`).record(
+    eventLog.eventsTotal,
+    attributes
+  );
+  histogram(meter, `${EVENT_LOG_METRIC_PREFIX}.resident_sessions`).record(
+    eventLog.residentSessions,
+    attributes
+  );
+}
+
+type HistogramInstrument = {
+  record: (value: number, attributes?: Attributes) => void;
+};
+
+const histograms = new WeakMap<Meter, Map<string, HistogramInstrument>>();
+
+function histogram(meter: Meter, name: string): HistogramInstrument {
+  let byName = histograms.get(meter);
+  if (byName === undefined) {
+    byName = new Map();
+    histograms.set(meter, byName);
+  }
+  const existing = byName.get(name);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const unit = name.endsWith("_bytes") ? "By" : "{count}";
+  const created = meter.createHistogram(name, { unit });
+  byName.set(name, created);
+  return created;
+}
+
+async function defaultPostSeries(
+  config: DatadogMemoryMetricsConfig,
+  body: string
+): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+  try {
+    const response = await fetch(config.seriesUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "DD-API-KEY": config.apiKey,
+      },
+      body,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function mb(bytes: number): string {
+  return (bytes / MB).toFixed(1);
+}
+
+function sanitizeTag(value: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_\-./:]+/g, "_");
+  return normalized === "" ? "unknown" : normalized;
+}

package/src/internal/serve-restart.ts

@@ -0,0 +1,120 @@
+/**
+ * Enter-to-restart for `serve` / `dev` on a TTY.
+ *
+ * In-process close+re-serve cannot reload every authored change: Node ESM
+ * caches transitive imports, and module-level state (tsx, singletons) survives.
+ * The parent process therefore supervises a worker and respawns it when the
+ * worker exits with {@link ENTER_RESTART_EXIT_CODE}.
+ */
+
+export const ENTER_RESTART_EXIT_CODE = 75;
+
+export const SERVE_RESTART_WORKER_ENV = "AGENT_SERVE_RESTART_WORKER";
+
+export interface ServeRestartProcess {
+  execPath: string;
+  execArgv: readonly string[];
+  argv: readonly string[];
+  env: NodeJS.ProcessEnv;
+}
+
+export interface ServeRestartSpawnPlan {
+  command: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+}
+
+export interface ServeRestartWorkerChild {
+  once(
+    event: "exit",
+    listener: (code: number | null, signal: NodeJS.Signals | null) => void
+  ): void;
+}
+
+export function isServeRestartWorker(
+  env: NodeJS.ProcessEnv = process.env
+): boolean {
+  return env[SERVE_RESTART_WORKER_ENV] === "1";
+}
+
+export function serveRestartSpawnPlan(
+  proc: ServeRestartProcess
+): ServeRestartSpawnPlan {
+  return {
+    command: proc.execPath,
+    args: [...proc.execArgv, ...proc.argv.slice(1)],
+    env: { ...proc.env, [SERVE_RESTART_WORKER_ENV]: "1" },
+  };
+}
+
+export function shouldRespawnServeWorker(
+  code: number | null,
+  signal: NodeJS.Signals | null
+): boolean {
+  return signal === null && code === ENTER_RESTART_EXIT_CODE;
+}
+
+/**
+ * Run the TTY Enter-to-restart supervisor: spawn this CLI as a worker, and
+ * respawn whenever the worker exits asking for a restart. Other exits
+ * (Ctrl-C drain, crash, bind failure) propagate to the caller.
+ */
+export async function runEnterRestartSupervisor(options: {
+  spawn: (
+    command: string,
+    args: string[],
+    spawnOptions: { stdio: "inherit"; env: NodeJS.ProcessEnv }
+  ) => ServeRestartWorkerChild;
+  proc?: ServeRestartProcess;
+  onRestart?: () => void;
+  installSignalGuards?: (handler: () => void) => () => void;
+}): Promise<number> {
+  const proc = options.proc ?? {
+    execPath: process.execPath,
+    execArgv: process.execArgv,
+    argv: process.argv,
+    env: process.env,
+  };
+  const plan = serveRestartSpawnPlan(proc);
+  const uninstallSignals = (
+    options.installSignalGuards ?? installDefaultSignalGuards
+  )(() => undefined);
+
+  try {
+    for (;;) {
+      const child = options.spawn(plan.command, plan.args, {
+        stdio: "inherit",
+        env: plan.env,
+      });
+      const { code, signal } = await waitForExit(child);
+      if (!shouldRespawnServeWorker(code, signal)) {
+        if (signal !== null) {
+          return 1;
+        }
+        return code ?? 1;
+      }
+      options.onRestart?.();
+    }
+  } finally {
+    uninstallSignals();
+  }
+}
+
+function waitForExit(
+  child: ServeRestartWorkerChild
+): Promise<{ code: number | null; signal: NodeJS.Signals | null }> {
+  return new Promise((resolve) => {
+    child.once("exit", (code, signal) => {
+      resolve({ code, signal });
+    });
+  });
+}
+
+function installDefaultSignalGuards(handler: () => void): () => void {
+  process.on("SIGINT", handler);
+  process.on("SIGTERM", handler);
+  return () => {
+    process.off("SIGINT", handler);
+    process.off("SIGTERM", handler);
+  };
+}

package/src/internal/server.ts

@@ -135,6 +135,10 @@ import {
   playgroundDevBasePath,
   startPlaygroundDevServer,
 } from "./playground/toolchain.js";
+import {
+  collectMemoryHealthFields,
+  sumEventLogStats,
+} from "./process-memory-telemetry.js";
 import {
   ReminderRunner,
   ReminderValidationError,
@@ -162,6 +166,13 @@ import {
 } from "./session-engine.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
 
+function memoryHealthFields(engines: readonly SessionEngine[]) {
+  return collectMemoryHealthFields({
+    eventLog: () =>
+      sumEventLogStats(engines.map((engine) => engine.eventLogMemoryStats())),
+  });
+}
+
 const MAX_BODY_BYTES = 32 * 1024 * 1024;
 
 /** `GET /v1/artifacts` limit defaults / ceiling. */
@@ -636,6 +647,7 @@ export async function startServer(
             slug,
             name: project.name,
           })),
+          ...memoryHealthFields(runtimes.map((runtime) => runtime.engine)),
         }),
     });
   }
@@ -1049,6 +1061,7 @@ function mountAgentRoutes(
         ok: true,
         name: project.name,
         version: packageVersion(),
+        ...memoryHealthFields([engine]),
       }),
   });
 

package/src/internal/session-engine.ts

@@ -91,7 +91,7 @@ import {
   namespacedKv,
   storageCasKv,
 } from "./durable-session-store.js";
-import { EventLogStore } from "./event-log.js";
+import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
@@ -112,6 +112,10 @@ import { validateToolInput } from "./json-schema.js";
 import { LedgerServing, newLedgerPodId } from "./ledger-serving.js";
 import { McpHost } from "./mcp-host.js";
 import type { OtelCollector } from "./otel/collector.js";
+import {
+  shouldStartProcessMemoryTelemetry,
+  startProcessMemoryTelemetry,
+} from "./process-memory-telemetry.js";
 import {
   buildSessionContextBlock,
   SCHEDULE_CHANNEL_PREFIX,
@@ -364,6 +368,7 @@ export class SessionEngine {
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
   private readonly otelHost: HostOtelSessionApi;
+  private readonly stopMemoryTelemetry: (() => void) | undefined;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -480,6 +485,14 @@ export class SessionEngine {
     }
     this.ledgerServing = this.buildLedgerServing(options);
     this.ledgerServing?.start();
+    this.stopMemoryTelemetry = shouldStartProcessMemoryTelemetry()
+      ? startProcessMemoryTelemetry({
+          agentName: options.project.name,
+          getEventLogStats: () => this.logs.memoryStats(),
+          logger: this.logger,
+          meter: options.otelMeter,
+        })
+      : undefined;
   }
 
   /**
@@ -3445,8 +3458,14 @@ export class SessionEngine {
       });
   }
 
+  /** In-process event-log residency (OOM-suspect cache vs durable count). */
+  eventLogMemoryStats(): EventLogMemoryStats {
+    return this.logs.memoryStats();
+  }
+
   /** Drain running turns, dispatches, and pending writes, then dispose. */
   async close(): Promise<void> {
+    this.stopMemoryTelemetry?.();
     this.approvals.cancelAll("deny");
     // Ledger deliveries spawn turns, so settle them before activeTurns.
     await this.ledgerServing?.close();

package/src/internal/slack-provision-client.ts

@@ -6,11 +6,11 @@
  *
  * Auth is the user API key sent directly as the bearer (the routes are
  * `wrapUserApiRoute` on the backend); there is no token exchange here.
- * The endpoints are gated on the `agent_serve_slack_provisioning` Statsig
- * gate and 404 when it is off — the error mapping says so instead of
- * "not found". Expected provisioning failures carry a stable JSON `code`
+ * The endpoints ride `requireAgentServeAccess` and 404 `{ error: "Not found" }`
+ * when Agent Serve is off — same mapping as other agent-sdk deploy 404s.
+ * Expected provisioning failures carry a stable JSON `code`
  * (`not_connected`, `insufficient_scopes`, `manager_reauth_required`,
- * `app_conflict`, `app_cap_reached`, `ratelimited`, `invalid_app_id`, …)
+ * `app_conflict`, `ratelimited`, `invalid_app_id`, …)
  * which flows through on {@link SlackProvisionApiError.code} so the CLI
  * can branch.
  */
@@ -398,8 +398,8 @@ function mapErrorResponse(
           { status: 404 }
         );
       }
-      // The gate-off body is exactly {error: "Not found"}; anything else
-      // (e.g. "App not found" on delete) is a real not-found to surface.
+      // `{ error: "Not found" }` is Agent Serve off (`requireAgentServeAccess`),
+      // not a Slack-only enrollment bar.
       if (serverError !== undefined && serverError !== "Not found") {
         return new SlackProvisionApiError(serverError, {
           status: 404,
@@ -407,7 +407,7 @@ function mapErrorResponse(
         });
       }
       return new SlackProvisionApiError(
-        `Not found — Cursor's "Add to Slack" provisioning (the agent_serve_slack_provisioning feature gate) is not enabled for this account yet.`,
+        `Not found — the agent_serve_mvp feature gate may not be enabled for your team.`,
         { status: 404 }
       );
     }