@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/legacy-command-guard.ts

@@ -1,66 +0,0 @@
-import { type AgentServeDeployClient, DeployApiError } from "./deploy-client.js";
-import { CLI_COMMAND_NAME } from "./distribution.js";
-
-/**
- * Classify a hosted slug by probing the v2 control plane.
- *
- * Only HTTP 404 means “not v2.” Auth, 5xx, and transport errors fail closed
- * so a v2 slug cannot fall through to `/internal/agent-serve`. That probe
- * shares the factory microlith path used by secrets; a factory outage will
- * also block legacy `--prod` until it recovers.
- */
-export async function deploymentArchitecture(args: {
-  client: AgentServeDeployClient;
-  teamId: number;
-  slug: string;
-}): Promise<"v1" | "v2"> {
-  try {
-    await args.client.getAgentkitDeploy({
-      teamId: args.teamId,
-      slug: args.slug,
-    });
-    return "v2";
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 404) {
-      return "v1";
-    }
-    throw error;
-  }
-}
-
-/** `run --prod` returns a delivery; read the session after it is allocated. */
-export function v2HostedVerifyHint(slug = "<slug>"): string {
-  return (
-    `\`${CLI_COMMAND_NAME} run --prod\` returns a delivery. ` +
-    `An accept without sessionId is expected. ` +
-    `Poll the delivery until the session is allocated, then ` +
-    `\`${CLI_COMMAND_NAME} session <ses_> --prod --slug ${slug}\`.`
-  );
-}
-
-export function unsupportedV2LegacyCommandError(slug: string): DeployApiError {
-  return new DeployApiError(
-    `This command is not supported for architecture v2 deployment "${slug}". ` +
-      `call and sessions stay on the v1 API. ${v2HostedVerifyHint(slug)}`,
-    409,
-  );
-}
-
-export function isUnsupportedV2LegacyCommandError(error: unknown): error is DeployApiError {
-  return (
-    error instanceof DeployApiError &&
-    error.status === 409 &&
-    error.message.includes("not supported for architecture v2")
-  );
-}
-
-export async function rejectV2ForLegacyCommand(args: {
-  client: AgentServeDeployClient;
-  teamId: number;
-  slug: string;
-}): Promise<void> {
-  const architecture = await deploymentArchitecture(args);
-  if (architecture === "v2") {
-    throw unsupportedV2LegacyCommandError(args.slug);
-  }
-}

package/src/internal/listen-port.ts

@@ -1,85 +0,0 @@
-/**
- * Bind an HTTP server to a port, with a clear next-port path when 3000 (or
- * whatever was requested) is already taken — a common onboarding failure.
- */
-
-import { once } from "node:events";
-import type { Server } from "node:http";
-import { CLI_COMMAND_NAME } from "./distribution.js";
-
-/** Default listen port for `serve` / `dev` when `--port` is omitted. */
-export const DEFAULT_SERVE_PORT = 3000;
-
-/** How many ports above the default to try when the default is taken. */
-const DEFAULT_PORT_FALLBACK_SPAN = 20;
-
-export function isAddrInUse(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    (error as { code?: unknown }).code === "EADDRINUSE"
-  );
-}
-
-export function formatPortInUseHint(port: number): string {
-  const next = port === 0 ? 3001 : port + 1;
-  return (
-    `port ${port} is already in use. ` +
-    `Try \`${CLI_COMMAND_NAME} dev --port ${next}\` or \`--port 0\` for any free port.`
-  );
-}
-
-/**
- * `server.listen` with fallback when the caller used the default port.
- * Explicit `--port N` (including `0`) fails immediately with a next-port hint.
- */
-export async function listenHttpServer(args: {
-  server: Server;
-  host: string;
-  port: number;
-  /** True when the caller passed `port` (including 0); skip fallback. */
-  portWasExplicit: boolean;
-  logger: (line: string) => void;
-}): Promise<number> {
-  const { server, host, logger } = args;
-  const startPort = args.port;
-  if (args.portWasExplicit || startPort === 0) {
-    try {
-      server.listen(startPort, host);
-      await once(server, "listening");
-    } catch (error) {
-      if (isAddrInUse(error)) {
-        throw new Error(formatPortInUseHint(startPort));
-      }
-      throw error;
-    }
-    const address = server.address();
-    if (address === null || typeof address === "string") {
-      throw new Error("server listening without an address");
-    }
-    return address.port;
-  }
-
-  const last = startPort + DEFAULT_PORT_FALLBACK_SPAN;
-  for (let port = startPort; port <= last; port++) {
-    try {
-      server.listen(port, host);
-      await once(server, "listening");
-      if (port !== startPort) {
-        logger(
-          `[agent-sdk] port ${startPort} in use; listening on ${port} instead (pass --port to pick)`,
-        );
-      }
-      return port;
-    } catch (error) {
-      if (!isAddrInUse(error)) {
-        throw error;
-      }
-      if (port === last) {
-        throw new Error(formatPortInUseHint(port));
-      }
-    }
-  }
-  throw new Error(formatPortInUseHint(last));
-}

package/src/internal/local-control-plane.ts

@@ -1,442 +0,0 @@
-/**
- * In-process control plane started with local `serve`. Owns schedule clocks
- * and reminder documents + clocks, then fires into the kit the same way the
- * Cursor backend does over HTTP when `--no-control-plane` is set.
- *
- * Reminder lifecycle (protocol v1): CP assigns id, arms timers, claims a due
- * fire once, invokes a guest executor with an immutable descriptor, and
- * applies the outcome with generation/fireCount CAS. Cancel/rekey racing an
- * in-flight execution bumps generation so a stale outcome cannot resurrect
- * the reminder. Legacy `fireReminder(id, fireCount)` remains for v1 runners.
- *
- * v2 ingest lives here: `routeContinuation` stamps the mailbox (July twin
- * of hosted `routeVerifiedIngressContinuation`), and `attachScmEvents`
- * owns the `/v0/scm-events` long poll. v1 keeps engine-side scm-events.
- * Hosted `--no-control-plane` v2 skips that poll — the hosted CP delivers.
- */
-
-import { join } from "node:path";
-import { type CronExpression, parseCron } from "./cron.js";
-import {
-  type LocalIngressContinuation,
-  type RouteLocalIngressContinuationInput,
-  routeLocalIngressContinuation,
-} from "./local-ingress.js";
-import type { PlatformTimers } from "./platform-timers.js";
-import {
-  applyOutcomeToRecord,
-  claimFromDescriptor,
-  intentToNewRecord,
-  REMINDER_CP_PROTOCOL_VERSION,
-  type ReminderControlPlane,
-  type ReminderCreateIntent,
-  type ReminderExecutionOutcome,
-  type ReminderFireClaim,
-  type ReminderGuestExecutor,
-  type ReminderOutcomeApplyResult,
-  recordGeneration,
-  toFireDescriptor,
-} from "./reminder-control-plane-protocol.js";
-import { MAX_TIMER_MS } from "./reminder-schedule.js";
-import { type ReminderRecord, ReminderStore } from "./reminder-store.js";
-
-export interface LocalControlPlane extends PlatformTimers, ReminderControlPlane {
-  /**
-   * Stamp a v2 mailbox from the channel selector + live payload. Same
-   * contract as hosted verified ingress. `/v1` is a no-op.
-   */
-  routeContinuation(input: RouteLocalIngressContinuationInput): LocalIngressContinuation;
-  /**
-   * Take ownership of the v2 `/v0/scm-events` long poll. Starts the relay.
-   * v1 scm-events stay on the engine serve path.
-   */
-  attachScmEvents(relay: { start(): void; stop(): Promise<void> }): void;
-  /** Arm persisted reminder clocks after the kit fire callback is live. */
-  startClocks(): void;
-  stop(): void;
-}
-
-export async function createLocalControlPlane(opts: {
-  fireSchedule: (name: string) => Promise<unknown>;
-  /**
-   * Legacy v1 path: CP calls this with (id, fireCount) and the runner mutates
-   * authoritative state. Prefer {@link executeReminder} for architecture v2.
-   */
-  fireReminder?: (id: string, fireCount: number) => Promise<unknown>;
-  /**
-   * Protocol guest executor. When set, due timers claim once, invoke this
-   * with an immutable descriptor, and apply the returned outcome via CAS.
-   */
-  executeReminder?: ReminderGuestExecutor;
-  /**
-   * Persist reminder documents under `<stateDir>/reminders`. Local serve
-   * passes `<stateRoot>/control-plane`.
-   */
-  stateDir?: string;
-  /** Arm deadline timers. Off in `--dev`. Defaults to true. */
-  armReminderClocks?: boolean;
-  logger?: (line: string) => void;
-}): Promise<LocalControlPlane> {
-  if (opts.fireReminder === undefined && opts.executeReminder === undefined) {
-    throw new Error("createLocalControlPlane requires fireReminder and/or executeReminder");
-  }
-
-  const logger = opts.logger ?? (() => {});
-  const armReminderClocks = opts.armReminderClocks !== false;
-  const store =
-    opts.stateDir === undefined ? undefined : new ReminderStore(join(opts.stateDir, "reminders"));
-  const schedules = new Map<string, CronExpression>();
-  const reminderTimers = new Map<string, NodeJS.Timeout>();
-  const reminders = new Map<string, ReminderRecord>(
-    ((await store?.list()) ?? []).map(record => [
-      record.id,
-      { ...record, generation: record.generation ?? 0 },
-    ]),
-  );
-  /** In-flight claims keyed by reminder id (single-flight per id). */
-  const inflight = new Map<string, ReminderFireClaim>();
-  let scheduleTimer: NodeJS.Timeout | undefined;
-  let lastFiredMinute = -1;
-  let scmRelay: { start(): void; stop(): Promise<void> } | undefined;
-
-  async function persist(record: ReminderRecord): Promise<void> {
-    reminders.set(record.id, record);
-    await store?.save(record);
-  }
-
-  function armScheduleTicker(): void {
-    if (scheduleTimer !== undefined || schedules.size === 0) {
-      return;
-    }
-    const now = Date.now();
-    const nextMinute = (Math.floor(now / 60_000) + 1) * 60_000;
-    scheduleTimer = setTimeout(() => tickSchedules(), nextMinute - now + 250);
-    scheduleTimer.unref?.();
-  }
-
-  function stopScheduleTicker(): void {
-    if (scheduleTimer === undefined) {
-      return;
-    }
-    clearTimeout(scheduleTimer);
-    scheduleTimer = undefined;
-  }
-
-  function tickSchedules(): void {
-    scheduleTimer = undefined;
-    const now = new Date();
-    const minute = Math.floor(now.getTime() / 60_000);
-    if (minute !== lastFiredMinute) {
-      lastFiredMinute = minute;
-      for (const [name, cron] of schedules) {
-        if (!cron.matches(now)) {
-          continue;
-        }
-        void opts.fireSchedule(name).catch(error => {
-          logger(
-            `[agent-sdk] schedule "${name}" dispatch failed: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-          );
-        });
-      }
-    }
-    armScheduleTicker();
-  }
-
-  function clearReminderTimer(id: string): void {
-    const timer = reminderTimers.get(id);
-    if (timer !== undefined) {
-      clearTimeout(timer);
-      reminderTimers.delete(id);
-    }
-  }
-
-  function armReminder(record: ReminderRecord): void {
-    clearReminderTimer(record.id);
-    if (record.status !== "armed") {
-      return;
-    }
-    const delay = Math.min(MAX_TIMER_MS, Math.max(0, record.nextFireAtMs - Date.now()));
-    const timer = setTimeout(() => {
-      reminderTimers.delete(record.id);
-      void onReminderDue(record.id).catch(error => {
-        logger(
-          `[agent-sdk] reminder "${record.id}" dispatch failed: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-      });
-    }, delay);
-    timer.unref?.();
-    reminderTimers.set(record.id, timer);
-  }
-
-  async function claimDue(id: string): Promise<ReminderRecord | undefined> {
-    const current = reminders.get(id);
-    if (current === undefined || current.status !== "armed") {
-      return undefined;
-    }
-    if (current.nextFireAtMs > Date.now() + 50) {
-      armReminder(current);
-      return undefined;
-    }
-    if (inflight.has(id)) {
-      return undefined;
-    }
-    const claimed: ReminderRecord = {
-      ...current,
-      status: "firing",
-      generation: recordGeneration(current),
-      updatedAt: new Date().toISOString(),
-    };
-    await persist(claimed);
-    inflight.set(id, {
-      id: claimed.id,
-      fireCount: claimed.fireCount,
-      generation: recordGeneration(claimed),
-    });
-    return claimed;
-  }
-
-  async function applyReminderOutcome(
-    claim: ReminderFireClaim,
-    outcome: ReminderExecutionOutcome,
-  ): Promise<ReminderOutcomeApplyResult> {
-    const current = reminders.get(claim.id);
-    if (current === undefined) {
-      inflight.delete(claim.id);
-      return { applied: false, reason: "missing" };
-    }
-    const result = applyOutcomeToRecord(current, claim, outcome);
-    inflight.delete(claim.id);
-    if (!result.applied) {
-      if (current.status === "armed" && armReminderClocks) {
-        armReminder(current);
-      }
-      return result;
-    }
-    await persist(result.record);
-    if (armReminderClocks && result.record.status === "armed") {
-      armReminder(result.record);
-    } else {
-      clearReminderTimer(result.record.id);
-    }
-    return result;
-  }
-
-  async function onReminderDue(id: string): Promise<void> {
-    // Protocol path: claim → guest execute → CAS apply.
-    if (opts.executeReminder !== undefined) {
-      const claimed = await claimDue(id);
-      if (claimed === undefined) {
-        return;
-      }
-      const descriptor = toFireDescriptor(claimed, Date.now());
-      let outcome: ReminderExecutionOutcome;
-      try {
-        outcome = await opts.executeReminder(descriptor);
-      } catch (error) {
-        logger(
-          `[agent-sdk] reminder "${id}" guest execution failed: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        outcome = {
-          kind: "retry",
-          delayMs: 1_000,
-          reason: "guest_error",
-        };
-      }
-      const result = await applyReminderOutcome(claimFromDescriptor(descriptor), outcome);
-      if (!result.applied) {
-        logger(`[agent-sdk] reminder "${id}" outcome not applied: ${result.reason}`);
-      }
-      return;
-    }
-
-    // Legacy v1: do not claim/firing — runner mutates via putReminder after fire.
-    const current = reminders.get(id);
-    if (current === undefined || current.status !== "armed") {
-      return;
-    }
-    if (current.nextFireAtMs > Date.now() + 50) {
-      armReminder(current);
-      return;
-    }
-    try {
-      await opts.fireReminder!(current.id, current.fireCount);
-    } catch (error) {
-      logger(
-        `[agent-sdk] reminder "${id}" dispatch failed: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  }
-
-  return {
-    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
-
-    routeContinuation: routeLocalIngressContinuation,
-
-    attachScmEvents(relay) {
-      scmRelay = relay;
-      relay.start();
-      logger("[agent-sdk] cursor-events: control-plane ingest started");
-    },
-
-    async upsertSchedule(input) {
-      schedules.set(input.name, parseCron(input.cron));
-      armScheduleTicker();
-    },
-
-    async deleteSchedule(name) {
-      schedules.delete(name);
-      if (schedules.size === 0) {
-        stopScheduleTicker();
-      }
-    },
-
-    async putReminder(record) {
-      const normalized: ReminderRecord = {
-        ...record,
-        generation: record.generation ?? 0,
-      };
-      await persist(normalized);
-      if (armReminderClocks && normalized.status === "armed") {
-        armReminder(normalized);
-        return;
-      }
-      clearReminderTimer(normalized.id);
-      if (normalized.status !== "firing") {
-        inflight.delete(normalized.id);
-      }
-    },
-
-    async getReminder(id) {
-      return reminders.get(id);
-    },
-
-    async listReminders() {
-      return [...reminders.values()];
-    },
-
-    async deleteReminder(id) {
-      clearReminderTimer(id);
-      inflight.delete(id);
-      reminders.delete(id);
-      await store?.delete(id);
-    },
-
-    async createReminder(intent: ReminderCreateIntent) {
-      if (intent.protocolVersion !== REMINDER_CP_PROTOCOL_VERSION) {
-        throw new Error(
-          `Unsupported reminder CP protocol version ${String(intent.protocolVersion)}`,
-        );
-      }
-      const record = intentToNewRecord(intent);
-      await persist(record);
-      if (armReminderClocks && record.status === "armed") {
-        armReminder(record);
-      }
-      return record;
-    },
-
-    async cancelReminder(id, reason = "explicit_cancel") {
-      const current = reminders.get(id);
-      if (current === undefined) {
-        return undefined;
-      }
-      if (
-        current.status === "completed" ||
-        current.status === "cancelled" ||
-        current.status === "disarmed"
-      ) {
-        return current;
-      }
-      clearReminderTimer(id);
-      inflight.delete(id);
-      const updated: ReminderRecord = {
-        ...current,
-        status: "cancelled",
-        disarmReason: reason,
-        generation: recordGeneration(current) + 1,
-        updatedAt: new Date().toISOString(),
-      };
-      await persist(updated);
-      return updated;
-    },
-
-    async rekeyReminders(channelId, oldToken, newToken) {
-      let n = 0;
-      for (const record of [...reminders.values()]) {
-        if (record.channelId !== channelId || record.continuationToken !== oldToken) {
-          continue;
-        }
-        if (record.status !== "armed" && record.status !== "firing") {
-          continue;
-        }
-        const wasInflight = inflight.has(record.id);
-        inflight.delete(record.id);
-        let updated: ReminderRecord = {
-          ...record,
-          continuationToken: newToken,
-          status: "armed",
-          generation: recordGeneration(record) + 1,
-          updatedAt: new Date().toISOString(),
-        };
-        // Interrupted in-flight fire: retry the same fireCount soon.
-        if (wasInflight) {
-          updated = {
-            ...updated,
-            nextFireAtMs: Math.min(updated.nextFireAtMs, Date.now()),
-          };
-        }
-        await persist(updated);
-        if (armReminderClocks) {
-          armReminder(updated);
-        }
-        n += 1;
-      }
-      return n;
-    },
-
-    applyReminderOutcome,
-
-    startClocks() {
-      for (const record of reminders.values()) {
-        if (record.status === "firing") {
-          // Restart hydration: treat interrupted fires as armed for retry
-          // even when clocks are not armed (status must still recover).
-          const restored: ReminderRecord = {
-            ...record,
-            status: "armed",
-            updatedAt: new Date().toISOString(),
-          };
-          void persist(restored).then(() => {
-            if (armReminderClocks) {
-              armReminder(restored);
-            }
-          });
-          continue;
-        }
-        if (armReminderClocks && record.status === "armed") {
-          armReminder(record);
-        }
-      }
-    },
-
-    stop() {
-      stopScheduleTicker();
-      for (const id of [...reminderTimers.keys()]) {
-        clearReminderTimer(id);
-      }
-      inflight.clear();
-      if (scmRelay !== undefined) {
-        void scmRelay.stop();
-        scmRelay = undefined;
-      }
-    },
-  };
-}

package/src/internal/local-env.ts

@@ -1,59 +0,0 @@
-/**
- * Loads an agent directory's env files (and each immediate child's, for
- * multi-agent hosts) into process.env. Load order per directory is
- * `.env.local` then `.env` — `process.loadEnvFile` never overrides, so
- * real env wins over both, and `.env.local` wins over checked-in `.env`
- * defaults. Values a previous call loaded are refreshed, so a reload
- * picks up edits made since.
- */
-
-import { existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
-
-// Not real env, so a reload has to clear them first: loadEnvFile skips
-// anything already in process.env, which would pin the first-boot values.
-let fileLoadedKeys = new Set<string>();
-
-export function loadAgentLocalEnv(dir: string): string[] {
-  for (const key of fileLoadedKeys) {
-    delete process.env[key];
-  }
-  const realKeys = new Set(Object.keys(process.env));
-  const loaded: string[] = [];
-  const tryLoad = (path: string): void => {
-    if (!existsSync(path)) {
-      return;
-    }
-    process.loadEnvFile(path);
-    loaded.push(path);
-  };
-  const trackLoadedKeys = (): void => {
-    fileLoadedKeys = new Set(Object.keys(process.env).filter(key => !realKeys.has(key)));
-  };
-  const tryLoadDir = (agentDir: string): void => {
-    // `.env.local` first so its values win over checked-in `.env` defaults
-    // under loadEnvFile's no-override semantics.
-    tryLoad(join(agentDir, ".env.local"));
-    tryLoad(join(agentDir, ".env"));
-  };
-
-  tryLoadDir(dir);
-
-  let children: string[];
-  try {
-    children = readdirSync(dir, { withFileTypes: true })
-      .filter(entry => entry.isDirectory() && !entry.name.startsWith("."))
-      .map(entry => entry.name);
-  } catch {
-    trackLoadedKeys();
-    return loaded;
-  }
-  for (const child of children) {
-    if (child === "node_modules") {
-      continue;
-    }
-    tryLoadDir(join(dir, child));
-  }
-  trackLoadedKeys();
-  return loaded;
-}