@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/reminder-control-plane-protocol.ts

@@ -1,482 +0,0 @@
-/**
- * Versioned internal reminder control-plane protocol.
- *
- * CP owns reminder id, status, fireCount, nextFireAt, claim, and
- * completion/rearm. The guest validates create input and executes an
- * immutable fire descriptor, returning a structured outcome. Cursor-hosted
- * HTTP CP is not implemented here; {@link ReminderControlPlane} is the
- * surface the next backend PR will speak.
- *
- * Not part of the public package API — keep behind the internal boundary.
- */
-
-import { randomBytes } from "node:crypto";
-import type { JsonObject, ReminderBusyPolicy, ReminderScheduleKind } from "../types.js";
-import { parseDuration } from "./duration.js";
-import {
-  nextCronFireMs,
-  ReminderValidationError,
-  type ResolvedSchedule,
-  resolveSchedule,
-} from "./reminder-schedule.js";
-import type { ReminderRecord } from "./reminder-store.js";
-
-/** Wire / persistence version for this control-plane protocol. */
-export const REMINDER_CP_PROTOCOL_VERSION = 1 as const;
-/** Each recurring/retry fire can spend a model turn and create hosted work. */
-export const REMINDER_CP_MIN_RECURRING_INTERVAL_MS = 60_000 as const;
-
-export type ReminderCpProtocolVersion = typeof REMINDER_CP_PROTOCOL_VERSION;
-
-/**
- * Normalized raw schedule for create intents (JSON-safe).
- * CP resolves this into nextFireAtMs / intervalMs — guests must not send
- * authoritative fire times.
- */
-export type ReminderScheduleSpec =
-  | { kind: "every"; every: string }
-  | { kind: "cron"; cron: string }
-  | { kind: "delay"; delay: string | number }
-  | { kind: "at"; at: string };
-
-/**
- * Guest → CP create intent. No id/status/fireCount/nextFireAt — CP assigns
- * those after resolving {@link ReminderScheduleSpec}.
- */
-export interface ReminderCreateIntent {
-  protocolVersion: ReminderCpProtocolVersion;
-  purpose: string;
-  channelId: string;
-  continuationToken: string;
-  target?: Record<string, unknown>;
-  schedule: ReminderScheduleSpec;
-  prompt?: string;
-  handler?: string;
-  args?: JsonObject;
-  hasRunHandler: boolean;
-  hasUntilFn: boolean;
-  untilPrompt?: string;
-  busyPolicy: ReminderBusyPolicy;
-}
-
-/**
- * Immutable fire descriptor issued after CP claim. Guest execution must not
- * mutate authoritative status/fireCount; it returns {@link ReminderExecutionOutcome}.
- */
-export interface ReminderFireDescriptor {
-  protocolVersion: ReminderCpProtocolVersion;
-  id: string;
-  /** Fire index being executed (equals record.fireCount at claim time). */
-  fireCount: number;
-  /** CAS generation captured at claim; cancel/rekey bumps it. */
-  generation: number;
-  purpose: string;
-  channelId: string;
-  continuationToken: string;
-  target?: Record<string, unknown>;
-  scheduleKind: ReminderScheduleKind;
-  scheduleValue: string;
-  intervalMs?: number;
-  prompt?: string;
-  handler?: string;
-  args?: JsonObject;
-  hasRunHandler: boolean;
-  hasUntilFn: boolean;
-  untilPrompt?: string;
-  busyPolicy: ReminderBusyPolicy;
-  /** Due time that triggered this claim. */
-  nextFireAtMs: number;
-  claimedAtMs: number;
-}
-
-/** Claim token used to apply an outcome exactly once for (id, fireCount, generation). */
-export interface ReminderFireClaim {
-  id: string;
-  fireCount: number;
-  generation: number;
-}
-
-/**
- * Wire-JSON-safe guest execution outcome. Retry is explicit and keyed by
- * (id, fireCount) — `"retry"` does not increment fireCount.
- * `reschedule.at` is an ISO-8601 string (never a Date).
- */
-export type ReminderExecutionOutcome =
-  | {
-      kind: "delivered";
-      /** Optional one-shot reschedule override (same as handler reschedule). */
-      reschedule?: ReminderWireReschedule;
-    }
-  | {
-      kind: "skipped";
-      reschedule?: ReminderWireReschedule;
-    }
-  | { kind: "stop"; reason: string }
-  | {
-      /** Re-arm the same fireCount after an explicit, idempotent retry. */
-      kind: "retry";
-      delayMs?: number;
-      reason?: string;
-    };
-
-/** JSON-safe reschedule override for outcomes / hosted wire. */
-export interface ReminderWireReschedule {
-  delay?: string | number;
-  /** ISO-8601 timestamp — never a Date instance. */
-  at?: string;
-}
-
-export type ReminderOutcomeApplyResult =
-  | { applied: true; record: ReminderRecord }
-  | {
-      applied: false;
-      reason: "missing" | "stale_generation" | "stale_fire_count" | "not_claimed" | "duplicate";
-      record?: ReminderRecord;
-    };
-
-/** Guest executor callback invoked by the CP after a successful claim. */
-export type ReminderGuestExecutor = (
-  descriptor: ReminderFireDescriptor,
-) => Promise<ReminderExecutionOutcome>;
-
-/**
- * Control-plane reminder API (local disk today; Cursor-hosted HTTP later).
- * Extends document CRUD with create-intent, cancel/rekey CAS, and outcome apply.
- */
-export interface ReminderControlPlane {
-  readonly protocolVersion: ReminderCpProtocolVersion;
-  createReminder(intent: ReminderCreateIntent): Promise<ReminderRecord>;
-  getReminder(id: string): Promise<ReminderRecord | undefined>;
-  listReminders(): Promise<ReminderRecord[]>;
-  cancelReminder(id: string, reason?: string): Promise<ReminderRecord | undefined>;
-  /**
-   * Re-key armed (and in-flight) reminders for a continuation rotation.
-   * Bumps generation so an in-flight outcome cannot land on the old token.
-   */
-  rekeyReminders(channelId: string, oldToken: string, newToken: string): Promise<number>;
-  applyReminderOutcome(
-    claim: ReminderFireClaim,
-    outcome: ReminderExecutionOutcome,
-  ): Promise<ReminderOutcomeApplyResult>;
-}
-
-export function newReminderId(): string {
-  return `rem_${randomBytes(8).toString("hex")}`;
-}
-
-export function recordGeneration(record: ReminderRecord): number {
-  return record.generation ?? 0;
-}
-
-/** Map a JSON-safe schedule spec into resolveSchedule create fields. */
-export function scheduleSpecToCreateFields(schedule: ReminderScheduleSpec): {
-  every?: string;
-  cron?: string;
-  delay?: string | number;
-  at?: string;
-} {
-  switch (schedule.kind) {
-    case "every":
-      return { every: schedule.every };
-    case "cron":
-      return { cron: schedule.cron };
-    case "delay":
-      return { delay: schedule.delay };
-    case "at":
-      return { at: schedule.at };
-  }
-}
-
-/**
- * Build a wire-safe schedule spec from guest create input.
- * Normalizes `at` Dates/numbers to ISO strings.
- */
-export function scheduleSpecFromCreateInput(input: {
-  every?: string;
-  cron?: string;
-  delay?: string | number;
-  at?: Date | string | number;
-}): ReminderScheduleSpec {
-  const shapes = [
-    input.every !== undefined,
-    input.cron !== undefined,
-    input.delay !== undefined,
-    input.at !== undefined,
-  ].filter(Boolean);
-  if (shapes.length !== 1) {
-    throw new ReminderValidationError(
-      "reminders.create requires exactly one of every, cron, delay, or at",
-    );
-  }
-  if (input.every !== undefined) {
-    return { kind: "every", every: input.every };
-  }
-  if (input.cron !== undefined) {
-    return { kind: "cron", cron: input.cron };
-  }
-  if (input.delay !== undefined) {
-    return { kind: "delay", delay: input.delay };
-  }
-  return { kind: "at", at: normalizeScheduleAt(input.at!) };
-}
-
-/**
- * Normalize a guest-facing `at` value to an ISO string for the wire intent.
- */
-export function normalizeScheduleAt(at: Date | string | number): string {
-  if (at instanceof Date) {
-    if (!Number.isFinite(at.getTime())) {
-      throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
-    }
-    return at.toISOString();
-  }
-  if (typeof at === "number") {
-    if (!Number.isFinite(at)) {
-      throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
-    }
-    return new Date(at).toISOString();
-  }
-  const ms = Date.parse(at);
-  if (!Number.isFinite(ms)) {
-    throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
-  }
-  // Preserve caller string when it already parses; still wire-safe.
-  return at;
-}
-
-/** Normalize handler reschedule into a wire-JSON-safe shape. */
-export function toWireReschedule(reschedule: {
-  delay?: string | number;
-  at?: Date | string;
-}): ReminderWireReschedule {
-  const out: ReminderWireReschedule = {};
-  if (reschedule.delay !== undefined) {
-    out.delay = reschedule.delay;
-  }
-  if (reschedule.at !== undefined) {
-    out.at = reschedule.at instanceof Date ? reschedule.at.toISOString() : String(reschedule.at);
-  }
-  return out;
-}
-
-/**
- * Build a durable record from a create intent. CP owns schedule resolution
- * via {@link resolveSchedule}; pass `nowMs` for deterministic tests.
- */
-export function intentToNewRecord(
-  intent: ReminderCreateIntent,
-  nowMs: number = Date.now(),
-): ReminderRecord {
-  if (intent.protocolVersion !== REMINDER_CP_PROTOCOL_VERSION) {
-    throw new ReminderValidationError(
-      `Unsupported reminder CP protocol version ${String(intent.protocolVersion)}`,
-    );
-  }
-  const resolved: ResolvedSchedule = resolveSchedule(
-    scheduleSpecToCreateFields(intent.schedule),
-    nowMs,
-  );
-  if (
-    resolved.kind === "every" &&
-    (resolved.intervalMs ?? 0) < REMINDER_CP_MIN_RECURRING_INTERVAL_MS
-  ) {
-    throw new ReminderValidationError(
-      `every must be >= 1m (got ${intent.schedule.kind === "every" ? intent.schedule.every : ""})`,
-    );
-  }
-  const nowIso = new Date(nowMs).toISOString();
-  return {
-    version: 1,
-    id: newReminderId(),
-    purpose: intent.purpose,
-    channelId: intent.channelId,
-    continuationToken: intent.continuationToken,
-    target: intent.target,
-    scheduleKind: resolved.kind,
-    scheduleValue: resolved.value,
-    intervalMs: resolved.intervalMs,
-    prompt: intent.prompt,
-    handler: intent.handler,
-    args: intent.args,
-    hasRunHandler: intent.hasRunHandler,
-    hasUntilFn: intent.hasUntilFn,
-    untilPrompt: intent.untilPrompt,
-    busyPolicy: intent.busyPolicy,
-    status: "armed",
-    fireCount: 0,
-    nextFireAtMs: resolved.nextFireAtMs,
-    generation: 0,
-    createdAt: nowIso,
-    updatedAt: nowIso,
-  };
-}
-
-export function toFireDescriptor(
-  record: ReminderRecord,
-  claimedAtMs: number,
-): ReminderFireDescriptor {
-  return {
-    protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
-    id: record.id,
-    fireCount: record.fireCount,
-    generation: recordGeneration(record),
-    purpose: record.purpose,
-    channelId: record.channelId,
-    continuationToken: record.continuationToken,
-    target: record.target,
-    scheduleKind: record.scheduleKind,
-    scheduleValue: record.scheduleValue,
-    intervalMs: record.intervalMs,
-    prompt: record.prompt,
-    handler: record.handler,
-    args: record.args,
-    hasRunHandler: record.hasRunHandler,
-    hasUntilFn: record.hasUntilFn,
-    untilPrompt: record.untilPrompt,
-    busyPolicy: record.busyPolicy,
-    nextFireAtMs: record.nextFireAtMs,
-    claimedAtMs,
-  };
-}
-
-export function claimFromDescriptor(descriptor: ReminderFireDescriptor): ReminderFireClaim {
-  return {
-    id: descriptor.id,
-    fireCount: descriptor.fireCount,
-    generation: descriptor.generation,
-  };
-}
-
-function resolveRescheduleMs(reschedule: ReminderWireReschedule, nowMs: number): number {
-  if (reschedule.delay !== undefined) {
-    return nowMs + parseDuration(reschedule.delay);
-  }
-  if (reschedule.at !== undefined) {
-    const atMs = Date.parse(reschedule.at);
-    if (!Number.isFinite(atMs)) {
-      throw new ReminderValidationError("Invalid reminder reschedule.at");
-    }
-    return atMs;
-  }
-  throw new ReminderValidationError("reminder reschedule requires delay or at");
-}
-
-/** Next fire time from the record's recurring schedule (CP-owned). */
-export function nextScheduleFireAtMs(record: ReminderRecord, afterMs: number): number {
-  if (record.scheduleKind === "every" && record.intervalMs !== undefined) {
-    return afterMs + record.intervalMs;
-  }
-  if (record.scheduleKind === "cron") {
-    return nextCronFireMs(record.scheduleValue, afterMs);
-  }
-  throw new ReminderValidationError(
-    `Cannot advance schedule for reminder "${record.id}" (kind=${record.scheduleKind})`,
-  );
-}
-
-export function isOneShotSchedule(kind: ReminderScheduleKind): boolean {
-  return kind === "delay" || kind === "at";
-}
-
-/**
- * Pure CAS apply of a guest outcome onto a reminder record.
- * Callers persist the returned record when `applied: true`.
- * Requires `status === "firing"` — an armed record was never claimed.
- */
-export function applyOutcomeToRecord(
-  record: ReminderRecord,
-  claim: ReminderFireClaim,
-  outcome: ReminderExecutionOutcome,
-  nowMs: number = Date.now(),
-): ReminderOutcomeApplyResult {
-  if (record.id !== claim.id) {
-    return { applied: false, reason: "missing", record };
-  }
-  // Prefer duplicate over generation mismatch: a successful prior apply
-  // bumps both fireCount and generation, and retries of (id, fireCount)
-  // must stay idempotent no-ops.
-  if (record.fireCount > claim.fireCount) {
-    return { applied: false, reason: "duplicate", record };
-  }
-  if (record.fireCount < claim.fireCount) {
-    return { applied: false, reason: "stale_fire_count", record };
-  }
-  if (recordGeneration(record) !== claim.generation) {
-    return { applied: false, reason: "stale_generation", record };
-  }
-  // Only a claimed (firing) reminder can accept an outcome.
-  if (record.status !== "firing") {
-    return { applied: false, reason: "not_claimed", record };
-  }
-
-  const nowIso = new Date(nowMs).toISOString();
-
-  if (outcome.kind === "retry") {
-    const delayMs = Math.max(
-      REMINDER_CP_MIN_RECURRING_INTERVAL_MS,
-      outcome.delayMs ?? REMINDER_CP_MIN_RECURRING_INTERVAL_MS,
-    );
-    const updated: ReminderRecord = {
-      ...record,
-      status: "armed",
-      nextFireAtMs: nowMs + delayMs,
-      // Same fireCount; bump generation so a second apply of the old claim is stale.
-      generation: recordGeneration(record) + 1,
-      updatedAt: nowIso,
-    };
-    return { applied: true, record: updated };
-  }
-
-  if (outcome.kind === "stop") {
-    const updated: ReminderRecord = {
-      ...record,
-      status: "completed",
-      disarmReason: outcome.reason,
-      fireCount: record.fireCount + 1,
-      generation: recordGeneration(record) + 1,
-      updatedAt: nowIso,
-    };
-    return { applied: true, record: updated };
-  }
-
-  const reschedule = outcome.reschedule;
-  if (reschedule !== undefined) {
-    const nextFireAtMs = resolveRescheduleMs(reschedule, nowMs);
-    const updated: ReminderRecord = {
-      ...record,
-      status: "armed",
-      fireCount: record.fireCount + 1,
-      nextFireAtMs,
-      scheduleKind: reschedule.delay !== undefined ? "delay" : "at",
-      scheduleValue:
-        reschedule.delay !== undefined ? String(reschedule.delay) : String(reschedule.at),
-      intervalMs: undefined,
-      generation: recordGeneration(record) + 1,
-      updatedAt: nowIso,
-    };
-    return { applied: true, record: updated };
-  }
-
-  if (isOneShotSchedule(record.scheduleKind)) {
-    const updated: ReminderRecord = {
-      ...record,
-      status: "completed",
-      disarmReason: outcome.kind === "skipped" ? "skipped_one_shot" : "one_shot_complete",
-      fireCount: record.fireCount + 1,
-      generation: recordGeneration(record) + 1,
-      updatedAt: nowIso,
-    };
-    return { applied: true, record: updated };
-  }
-
-  const nextFireAtMs = nextScheduleFireAtMs(record, nowMs);
-  const updated: ReminderRecord = {
-    ...record,
-    status: "armed",
-    fireCount: record.fireCount + 1,
-    nextFireAtMs,
-    generation: recordGeneration(record) + 1,
-    updatedAt: nowIso,
-  };
-  return { applied: true, record: updated };
-}