@cursor/july 0.1.48 → 0.1.51

package/src/internal/convert-automation/convert-workflow.ts

@@ -999,7 +999,7 @@ function emitSlackChannel(
   }
   if (socketMode) {
     out.setupSteps.push(
-      `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app (not the Cursor connection): run \`${CLI_COMMAND_NAME} slack setup\`, then \`${CLI_COMMAND_NAME} slack init --channel-posts\`, and set the generated tokens.`
+      `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app (not the Cursor connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
     );
   }
 
@@ -1069,7 +1069,7 @@ function emitSlackChannel(
     body = [
       "//",
       "// This channel needs a dedicated Socket Mode Slack app (not the Cursor",
-      `// connection): run \`${CLI_COMMAND_NAME} slack setup\` and \`${CLI_COMMAND_NAME} slack init\`.`,
+      `// connection): run \`${CLI_COMMAND_NAME} slack create --channel-posts\`.`,
       "export default slackChannel({",
       ...engagement,
       "});",

package/src/internal/event-log.ts

@@ -59,6 +59,17 @@ export class SessionEventLog {
     return this.events.length;
   }
 
+  /**
+   * In-process residency vs recorded length. Today those are the same
+   * (`events` is the cache). A later change can drop the cache and keep
+   * `eventsTotal` as the durable count while `eventsRetained` shrinks to
+   * the unflushed tail.
+   */
+  memoryStats(): { eventsRetained: number; eventsTotal: number } {
+    const n = this.events.length;
+    return { eventsRetained: n, eventsTotal: n };
+  }
+
   /**
    * Assign the next index, record the event, and fan out to live
    * subscribers. Ordering is synchronous; file persistence is chained in
@@ -154,9 +165,16 @@ export class SessionEventLog {
   }
 }
 
+export type EventLogMemoryStats = {
+  residentSessions: number;
+  eventsRetained: number;
+  eventsTotal: number;
+};
+
 /** Lazily opens one {@link SessionEventLog} per session. */
 export class EventLogStore {
   private readonly logs = new Map<string, Promise<SessionEventLog>>();
+  private readonly opened = new Map<string, SessionEventLog>();
 
   constructor(
     private readonly eventFilePathFor: (sessionId: string) => string,
@@ -170,18 +188,38 @@ export class EventLogStore {
     let log = this.logs.get(sessionId);
     if (log === undefined) {
       const filePath = this.eventFilePathFor(sessionId);
-      log = mkdir(dirname(filePath), { recursive: true }).then(() =>
-        SessionEventLog.open({
-          sessionId,
-          filePath,
-          onPersistError: (error) => this.onPersistError(sessionId, error),
-        })
-      );
+      log = mkdir(dirname(filePath), { recursive: true })
+        .then(() =>
+          SessionEventLog.open({
+            sessionId,
+            filePath,
+            onPersistError: (error) => this.onPersistError(sessionId, error),
+          })
+        )
+        .then((opened) => {
+          this.opened.set(sessionId, opened);
+          return opened;
+        });
       this.logs.set(sessionId, log);
     }
     return log;
   }
 
+  memoryStats(): EventLogMemoryStats {
+    let eventsRetained = 0;
+    let eventsTotal = 0;
+    for (const log of this.opened.values()) {
+      const stats = log.memoryStats();
+      eventsRetained += stats.eventsRetained;
+      eventsTotal += stats.eventsTotal;
+    }
+    return {
+      residentSessions: this.logs.size,
+      eventsRetained,
+      eventsTotal,
+    };
+  }
+
   async flushAll(): Promise<void> {
     await Promise.all(
       [...this.logs.values()].map((logPromise) =>

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/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();