@cursor/july 0.1.104 → 0.1.107

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

@@ -0,0 +1,499 @@
+/**
+ * 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;
+
+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
+  );
+  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 = outcome.delayMs ?? 0;
+    const updated: ReminderRecord = {
+      ...record,
+      status: "armed",
+      nextFireAtMs: nowMs + Math.max(0, 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 };
+}