@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/platform-schedule-sync.ts

@@ -1,75 +0,0 @@
-/**
- * Keep control-plane Temporal calendars aligned with authored
- * `agent/schedules/*`. Upsert current names and delete ones that disappeared
- * since the last successful sync (persisted under the engine state root).
- */
-
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-
-import type { PlatformTimers } from "./platform-timers.js";
-
-export const PLATFORM_SCHEDULE_CATALOG_FILENAME = "platform-schedule-names.json";
-
-export async function syncHostedPlatformSchedules(args: {
-  timers: PlatformTimers;
-  schedules: ReadonlyArray<{ name: string; cron: string }>;
-  catalogPath: string;
-  logger: (line: string) => void;
-}): Promise<void> {
-  const previous = await readScheduleCatalog(args.catalogPath);
-  const currentNames = args.schedules.map(schedule => schedule.name);
-  const currentSet = new Set(currentNames);
-
-  const failedDeletes: string[] = [];
-  for (const name of previous) {
-    if (currentSet.has(name)) {
-      continue;
-    }
-    try {
-      await args.timers.deleteSchedule(name);
-    } catch (error) {
-      failedDeletes.push(name);
-      args.logger(
-        `[agent-sdk] platform timer delete failed for schedule "${name}": ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  }
-
-  for (const schedule of args.schedules) {
-    try {
-      await args.timers.upsertSchedule({
-        name: schedule.name,
-        cron: schedule.cron,
-      });
-    } catch (error) {
-      args.logger(
-        `[agent-sdk] platform timer upsert failed for schedule "${schedule.name}": ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  }
-
-  // Keep failed removals in the catalog so the next boot retries them.
-  await writeScheduleCatalog(args.catalogPath, [...new Set([...currentNames, ...failedDeletes])]);
-}
-
-async function readScheduleCatalog(catalogPath: string): Promise<string[]> {
-  try {
-    const parsed: unknown = JSON.parse(await readFile(catalogPath, "utf8"));
-    if (!Array.isArray(parsed)) {
-      return [];
-    }
-    return parsed.filter((entry): entry is string => typeof entry === "string");
-  } catch {
-    return [];
-  }
-}
-
-async function writeScheduleCatalog(catalogPath: string, names: readonly string[]): Promise<void> {
-  await mkdir(dirname(catalogPath), { recursive: true });
-  await writeFile(catalogPath, `${JSON.stringify(names)}\n`, "utf8");
-}

package/src/internal/platform-timers.ts

@@ -1,365 +0,0 @@
-/**
- * Timed-work client used by the kit. Local serve implements this in-process
- * (`createLocalControlPlane`). Cursor hosting (`--no-control-plane`) uses
- * the HTTP client below against the Cursor backend. Authors never see this
- * surface.
- *
- * The control plane owns reminder *documents* and clocks. The kit only
- * executes fires.
- */
-
-import {
-  REMINDER_CP_PROTOCOL_VERSION,
-  type ReminderControlPlane,
-  type ReminderCreateIntent,
-  type ReminderExecutionOutcome,
-  type ReminderFireClaim,
-  type ReminderOutcomeApplyResult,
-} from "./reminder-control-plane-protocol.js";
-import { isReminderRecord, type ReminderRecord } from "./reminder-store.js";
-
-const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-
-export interface PlatformTimers {
-  upsertSchedule(input: { name: string; cron: string }): Promise<void>;
-  deleteSchedule(name: string): Promise<void>;
-  putReminder(record: ReminderRecord): Promise<void>;
-  getReminder(id: string): Promise<ReminderRecord | undefined>;
-  listReminders(): Promise<ReminderRecord[]>;
-  deleteReminder(id: string): Promise<void>;
-}
-
-export interface CursorHostedPlatformTimersOptions {
-  baseUrl?: string;
-  apiKey?: string;
-  fetch?: typeof fetch;
-}
-
-function resolveApiKey(options: CursorHostedPlatformTimersOptions): string {
-  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error(
-      "platform timers require CURSOR_API_KEY (deployment pod credential on Cursor hosting)",
-    );
-  }
-  return key;
-}
-
-function resolveBaseUrl(options: CursorHostedPlatformTimersOptions): string {
-  const raw = (
-    options.baseUrl ??
-    process.env.CURSOR_API_BASE_URL ??
-    DEFAULT_CURSOR_EXTERNAL_API_URL
-  ).trim();
-  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
-}
-
-async function timedWorkFetch(
-  options: CursorHostedPlatformTimersOptions,
-  method: "GET" | "PUT" | "DELETE",
-  path: string,
-  body?: unknown,
-): Promise<Response> {
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
-    throw new Error("platform timers require fetch");
-  }
-  return fetchImpl(`${resolveBaseUrl(options)}${path}`, {
-    method,
-    headers: {
-      Authorization: `Bearer ${resolveApiKey(options)}`,
-      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
-    },
-    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-  });
-}
-
-async function timedWorkRpc(
-  options: CursorHostedPlatformTimersOptions,
-  method: "PUT" | "DELETE",
-  path: string,
-  body?: unknown,
-): Promise<void> {
-  const response = await timedWorkFetch(options, method, path, body);
-  if (response.ok) {
-    return;
-  }
-  const text = await response.text();
-  let detail = `HTTP ${response.status}`;
-  try {
-    const parsed: unknown = text.length === 0 ? {} : JSON.parse(text);
-    if (
-      parsed !== null &&
-      typeof parsed === "object" &&
-      "error" in parsed &&
-      typeof (parsed as { error: unknown }).error === "string"
-    ) {
-      detail = (parsed as { error: string }).error;
-    }
-  } catch {
-    // Keep the status-only detail.
-  }
-  throw new Error(`platform timers ${method} ${path}: ${detail}`);
-}
-
-export function createCursorHostedPlatformTimers(
-  options: CursorHostedPlatformTimersOptions = {},
-): PlatformTimers {
-  return {
-    async upsertSchedule(input) {
-      await timedWorkRpc(
-        options,
-        "PUT",
-        `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(input.name)}`,
-        { cron: input.cron },
-      );
-    },
-    async deleteSchedule(name) {
-      await timedWorkRpc(
-        options,
-        "DELETE",
-        `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(name)}`,
-      );
-    },
-    async putReminder(record) {
-      await timedWorkRpc(
-        options,
-        "PUT",
-        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(record.id)}`,
-        record,
-      );
-    },
-    async getReminder(id) {
-      const response = await timedWorkFetch(
-        options,
-        "GET",
-        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`,
-      );
-      if (response.status === 404) {
-        return undefined;
-      }
-      if (!response.ok) {
-        throw new Error(`platform timers GET /reminders/${id}: HTTP ${response.status}`);
-      }
-      const parsed: unknown = await response.json();
-      return isReminderRecord(parsed) ? parsed : undefined;
-    },
-    async listReminders() {
-      const response = await timedWorkFetch(
-        options,
-        "GET",
-        "/internal/agent-serve/timed-work/reminders",
-      );
-      if (!response.ok) {
-        throw new Error(`platform timers GET /reminders: HTTP ${response.status}`);
-      }
-      const parsed: unknown = await response.json();
-      if (
-        parsed === null ||
-        typeof parsed !== "object" ||
-        !("reminders" in parsed) ||
-        !Array.isArray((parsed as { reminders: unknown }).reminders)
-      ) {
-        return [];
-      }
-      return (parsed as { reminders: unknown[] }).reminders.filter(isReminderRecord);
-    },
-    async deleteReminder(id) {
-      await timedWorkRpc(
-        options,
-        "DELETE",
-        `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`,
-      );
-    },
-  };
-}
-
-/** v2 reminder CP is factory ECS (`/internal/agentsdk/*`), not timed-work. */
-const AGENTSDK_REMINDERS_PREFIX = "/internal/agentsdk";
-
-/**
- * Bounded retries for idempotent CP outcome writes after the guest handler
- * has already run. Delivery is at-least-once: a transient apply failure may
- * re-enter the handler on the next Temporal admission. Do not claim
- * exactly-once handler execution.
- */
-const APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS = 3;
-const APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS = 50;
-
-async function sleepMs(ms: number): Promise<void> {
-  await new Promise(resolve => setTimeout(resolve, ms));
-}
-
-async function withBoundedApplyRetries<T>(run: () => Promise<T>): Promise<T> {
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS; attempt++) {
-    try {
-      return await run();
-    } catch (error) {
-      lastError = error;
-      if (attempt >= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS) {
-        break;
-      }
-      await sleepMs(APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS * attempt);
-    }
-  }
-  throw lastError;
-}
-
-async function timedWorkJsonFetch(
-  options: CursorHostedPlatformTimersOptions,
-  method: "GET" | "POST" | "PUT" | "DELETE",
-  path: string,
-  body?: unknown,
-): Promise<Response> {
-  const fetchImpl = options.fetch ?? globalThis.fetch;
-  if (typeof fetchImpl !== "function") {
-    throw new Error("reminder control plane requires fetch");
-  }
-  return fetchImpl(`${resolveBaseUrl(options)}${path}`, {
-    method,
-    headers: {
-      Authorization: `Bearer ${resolveApiKey(options)}`,
-      ...(body === undefined ? {} : { "Content-Type": "application/json" }),
-    },
-    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-  });
-}
-
-const CP_ERROR_BODY_LIMIT = 512;
-
-/**
- * Read failures carry status and a bounded body: the guest logs them once
- * per process, and a 405 body names the route the caller should be on.
- */
-async function reminderCpReadError(what: string, response: Response): Promise<Error> {
-  let body = "";
-  try {
-    body = (await response.text()).trim();
-  } catch {
-    // Status-only detail.
-  }
-  const detail = body === "" ? "" : ` ${body.slice(0, CP_ERROR_BODY_LIMIT)}`;
-  return new Error(`reminder CP ${what} failed: HTTP ${response.status}${detail}`);
-}
-
-/**
- * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
- * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
- * CP owns ids and time. v1 PUT/DELETE reminders stay on timed-work.
- */
-export function createCursorHostedReminderControlPlane(
-  options: CursorHostedPlatformTimersOptions = {},
-): ReminderControlPlane {
-  return {
-    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
-    async createReminder(intent: ReminderCreateIntent) {
-      const response = await timedWorkJsonFetch(
-        options,
-        "POST",
-        `${AGENTSDK_REMINDERS_PREFIX}/reminders`,
-        intent,
-      );
-      if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`reminder CP create failed: HTTP ${response.status} ${text}`);
-      }
-      const parsed: unknown = await response.json();
-      if (!isReminderRecord(parsed)) {
-        throw new Error("reminder CP create returned invalid record");
-      }
-      return parsed;
-    },
-    async getReminder(id) {
-      const response = await timedWorkJsonFetch(
-        options,
-        "GET",
-        `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}`,
-      );
-      if (response.status === 404) {
-        return undefined;
-      }
-      if (!response.ok) {
-        throw await reminderCpReadError("get", response);
-      }
-      const parsed: unknown = await response.json();
-      return isReminderRecord(parsed) ? parsed : undefined;
-    },
-    async listReminders() {
-      const response = await timedWorkJsonFetch(
-        options,
-        "GET",
-        `${AGENTSDK_REMINDERS_PREFIX}/reminders`,
-      );
-      if (!response.ok) {
-        throw await reminderCpReadError("list", response);
-      }
-      const parsed: unknown = await response.json();
-      if (
-        parsed === null ||
-        typeof parsed !== "object" ||
-        !("reminders" in parsed) ||
-        !Array.isArray((parsed as { reminders: unknown }).reminders)
-      ) {
-        return [];
-      }
-      return (parsed as { reminders: unknown[] }).reminders.filter(isReminderRecord);
-    },
-    async cancelReminder(id, reason) {
-      const response = await timedWorkJsonFetch(
-        options,
-        "POST",
-        `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}/cancel`,
-        reason === undefined ? {} : { reason },
-      );
-      if (response.status === 404) {
-        return undefined;
-      }
-      if (!response.ok) {
-        throw new Error(`reminder CP cancel failed: HTTP ${response.status}`);
-      }
-      const parsed: unknown = await response.json();
-      return isReminderRecord(parsed) ? parsed : undefined;
-    },
-    async rekeyReminders(channelId, oldToken, newToken) {
-      const response = await timedWorkJsonFetch(
-        options,
-        "POST",
-        `${AGENTSDK_REMINDERS_PREFIX}/reminders/rekey`,
-        { channelId, oldToken, newToken },
-      );
-      if (!response.ok) {
-        throw new Error(`reminder CP rekey failed: HTTP ${response.status}`);
-      }
-      const parsed: unknown = await response.json();
-      if (
-        parsed === null ||
-        typeof parsed !== "object" ||
-        typeof (parsed as { count?: unknown }).count !== "number"
-      ) {
-        throw new Error("reminder CP rekey returned invalid body");
-      }
-      return (parsed as { count: number }).count;
-    },
-    async applyReminderOutcome(
-      claim: ReminderFireClaim,
-      outcome: ReminderExecutionOutcome,
-    ): Promise<ReminderOutcomeApplyResult> {
-      // Handler side effects may already have run; retry only the idempotent
-      // CP write. Exhausted failures stay thrown so Temporal can re-admit
-      // (at-least-once — not exactly-once).
-      return await withBoundedApplyRetries(async () => {
-        const response = await timedWorkJsonFetch(
-          options,
-          "POST",
-          `${AGENTSDK_REMINDERS_PREFIX}/reminders/outcome`,
-          { claim, outcome },
-        );
-        if (!response.ok) {
-          throw new Error(`reminder CP outcome apply failed: HTTP ${response.status}`);
-        }
-        return (await response.json()) as ReminderOutcomeApplyResult;
-      });
-    },
-  };
-}