@cursor/bdk 0.2.3 → 0.2.4

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

@@ -1,334 +0,0 @@
-/**
- * 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 residency is `event_log.resident_sessions` (open session
- * map). Transcripts live on disk; unflushed tails are not a scrape gauge.
- */
-
-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: Pick<EventLogMemoryStats, "residentSessions">;
-};
-
-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: { residentSessions: eventLog.residentSessions },
-  };
-}
-
-/**
- * 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}`
-  );
-}
-
-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,
-    },
-  ];
-  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}.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/project-layout.ts

@@ -1,31 +0,0 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-
-export type ProjectRoot = "bot" | "agent";
-
-export const CANONICAL_PROJECT_ROOT: ProjectRoot = "bot";
-
-export function resolveProjectRoot(rootDir: string): ProjectRoot {
-  if (existsSync(join(rootDir, "bot"))) {
-    return "bot";
-  }
-  if (existsSync(join(rootDir, "agent"))) {
-    return "agent";
-  }
-  return CANONICAL_PROJECT_ROOT;
-}
-
-export function projectPath(projectRoot: ProjectRoot, relativePath: string): string {
-  return `${projectRoot}/${relativePath}`;
-}
-
-export function remapCanonicalProjectPath(path: string, projectRoot: ProjectRoot): string {
-  if (projectRoot === CANONICAL_PROJECT_ROOT || !path.startsWith("bot/")) {
-    return path;
-  }
-  return `agent/${path.slice("bot/".length)}`;
-}
-
-export function remapCanonicalProjectContents(contents: string, projectRoot: ProjectRoot): string {
-  return projectRoot === CANONICAL_PROJECT_ROOT ? contents : contents.replaceAll("bot/", "agent/");
-}

package/src/internal/prompt-context.ts

@@ -1,116 +0,0 @@
-/**
- * Framework-authored prompt context. Two pieces:
- *
- * 1. Identity section — static, appended to the agent's instructions (local
- *    AGENTS.md and cloud first-turn preamble) so the model knows its own
- *    name and how messages and sessions reach it.
- * 2. Session context block — dynamic, prepended to the first turn's user
- *    prompt only, telling the model which session/channel/environment it is
- *    in plus a channel-appropriate presence line.
- */
-
-import type { ResolvedAgent } from "../types.js";
-
-export const SCHEDULE_CHANNEL_PREFIX = "schedule:";
-
-export type PromptEnvironment = "hosted deployment" | "local dev server";
-
-export function buildIdentitySection(agent: Pick<ResolvedAgent, "name" | "description">): string {
-  const description = agent.description?.trim().replace(/\.$/, "");
-  const intro =
-    description === undefined || description === ""
-      ? `You are "${agent.name}".`
-      : `You are "${agent.name}" — ${description}.`;
-  return [
-    "## About you",
-    "",
-    `${intro} You run as a persistent service: messages reach you through channels (such as Slack, GitHub, webhooks, or a web playground), and each conversation is a session that can continue across multiple turns.`,
-  ].join("\n");
-}
-
-export interface SessionContextInput {
-  sessionId: string;
-  channelId: string;
-  /**
-   * The channel pack's `meta.kind` (e.g. `"slack"`, `"github"`). Channel ids
-   * are file stems, so kind — not id — identifies what the channel is.
-   */
-  channelKind?: string;
-  environment: PromptEnvironment;
-  /**
-   * Injectable clock for tests; defaults to the mocked prompt time when
-   * `CURSOR_SDK_MOCK_PROMPT_TIME` is set, then to now.
-   */
-  now?: Date;
-}
-
-/**
- * Development-only override for the wall clock rendered into prompt content.
- * Same variable the Cursor SDK harness reads for its prompt clock (the
- * user-message <timestamp> prefix and user_info date), so one knob keeps the
- * session context block and the harness-rendered clock consistent. Read on
- * every render so a simulation harness can advance the instant between
- * sessions. Never affects runtime clocks (schedules, reminders) or tools.
- */
-const MOCK_PROMPT_TIME_ENV = "CURSOR_SDK_MOCK_PROMPT_TIME";
-
-function readMockPromptTimeFromEnv(): Date | undefined {
-  const raw = process.env[MOCK_PROMPT_TIME_ENV];
-  if (raw === undefined || raw === "") {
-    return undefined;
-  }
-  const parsed = new Date(raw);
-  return Number.isNaN(parsed.getTime()) ? undefined : parsed;
-}
-
-export function buildSessionContextBlock(input: SessionContextInput): string {
-  const now = input.now ?? readMockPromptTimeFromEnv() ?? new Date();
-  const lines = [
-    "<agentkit_context>",
-    `session: ${input.sessionId}`,
-    `channel: ${input.channelId}`,
-    `environment: ${input.environment}`,
-    `time: ${now.toISOString()}`,
-    "</agentkit_context>",
-  ];
-  const presence = channelPresenceLine(input);
-  if (presence !== undefined) {
-    lines.push(presence);
-  }
-  return lines.join("\n");
-}
-
-/**
- * One line telling the model whether anyone is watching this session and
- * where its output lands. Resolved from the channel pack's declared kind
- * when present, falling back to the built-in channel ids. Unknown channels
- * get no line rather than a guess.
- */
-export function channelPresenceLine(
-  channel: Pick<SessionContextInput, "channelId" | "channelKind">,
-): string | undefined {
-  const kind = channel.channelKind ?? builtinChannelKind(channel.channelId);
-  switch (kind) {
-    case "http":
-    case "mcp":
-      return "A user is interacting with you live and sees your replies as they stream.";
-    case "slack":
-      return "You are replying in a Slack thread; participants will read your messages.";
-    case "github":
-      return "You were triggered by a GitHub event. Deliver results through the actions available to you (comments, reviews, PRs); nobody sees your raw output otherwise.";
-    case "schedule":
-      return "This run was triggered automatically. No user is watching; complete the task autonomously and deliver results through your available tools/channels.";
-    default:
-      return undefined;
-  }
-}
-
-function builtinChannelKind(channelId: string): string | undefined {
-  if (channelId === "http" || channelId === "mcp") {
-    return channelId;
-  }
-  if (channelId.startsWith(SCHEDULE_CHANNEL_PREFIX)) {
-    return "schedule";
-  }
-  return undefined;
-}