@cursor/july 0.1.105 → 0.1.107

package/src/internal/reminder-runner.ts

@@ -1,20 +1,35 @@
 /**
  * Per-session reminder runner: durable wake subscriptions with
- * prompt XOR run, every/cron/delay/at schedules, and until as
- * function XOR prompt.
+ * prompt XOR named handler XOR run, every/cron/delay/at schedules, and
+ * until as function XOR prompt.
  */
 
 import { randomBytes } from "node:crypto";
 import type {
   AuthContext,
+  DiscoveredReminder,
+  JsonObject,
+  JsonValue,
   ReminderCreateInput,
+  ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
   ReminderInfo,
+  ReminderStatus,
   ReminderUntilContext,
 } from "../types.js";
+import { NAME_PATTERN } from "./discovery/names.js";
 import { parseDuration } from "./duration.js";
 import type { PlatformTimers } from "./platform-timers.js";
+import {
+  REMINDER_CP_PROTOCOL_VERSION,
+  type ReminderControlPlane,
+  type ReminderCreateIntent,
+  type ReminderExecutionOutcome,
+  type ReminderFireDescriptor,
+  scheduleSpecFromCreateInput,
+  toWireReschedule,
+} from "./reminder-control-plane-protocol.js";
 import {
   defaultBusyPolicy,
   MAX_TIMER_MS,
@@ -28,6 +43,9 @@ import { SessionBusyError, type SessionEngine } from "./session-engine.js";
 
 export { ReminderValidationError } from "./reminder-schedule.js";
 
+/** Max UTF-8 byte length of `JSON.stringify(args)` on named-handler create. */
+export const REMINDER_ARGS_MAX_BYTES: number = 32 * 1024;
+
 export class UnknownReminderError extends Error {
   constructor(
     reminderId: string,
@@ -43,10 +61,79 @@ interface LiveHandlers {
   untilFn?: (ctx: ReminderUntilContext) => Promise<boolean>;
 }
 
+export interface ReminderRunnerOptions {
+  /** Discovered `agent/reminders/*` handlers, keyed by module stem. */
+  namedHandlers?: readonly DiscoveredReminder[];
+  /**
+   * Architecture v2: reject anonymous `run` and function `until` at create
+   * (named `handler` + prompt remain), whether local or hosted.
+   */
+  rejectAnonymousHandlers?: boolean;
+  /**
+   * When set (local self-hosted architecture v2), create/cancel/rekey go
+   * through the control-plane protocol and fires are guest executions of
+   * immutable descriptors.
+   */
+  controlPlane?: ReminderControlPlane;
+  /** Agent architecture; used with {@link controlPlane} for v2 protocol path. */
+  architecture?: "v1" | "v2";
+}
+
+/**
+ * Server wiring for {@link ReminderRunnerOptions.rejectAnonymousHandlers}:
+ * architecture v2 always rejects anonymous run/until (local or hosted).
+ */
+export function rejectAnonymousReminderHandlers(options: {
+  noControlPlane?: boolean;
+  architecture?: string;
+}): boolean {
+  return options.architecture === "v2";
+}
+
 function newReminderId(): string {
   return `rem_${randomBytes(8).toString("hex")}`;
 }
 
+function isJsonObject(value: unknown): value is JsonObject {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.values(value as Record<string, unknown>).every(isJsonValue)
+  );
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value);
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  return isJsonObject(value);
+}
+
+/** Same stem rules as `agent/reminders/<name>.ts` discovery. */
+function isValidReminderHandlerName(name: string): boolean {
+  return NAME_PATTERN.test(name) && !name.includes("__");
+}
+
+function assertReminderArgsSize(args: JsonObject): void {
+  const bytes = Buffer.byteLength(JSON.stringify(args), "utf8");
+  if (bytes > REMINDER_ARGS_MAX_BYTES) {
+    throw new ReminderValidationError(
+      `reminders.create args exceed ${REMINDER_ARGS_MAX_BYTES} bytes (got ${bytes})`
+    );
+  }
+}
+
 function toInfo(record: ReminderRecord): ReminderInfo {
   return {
     id: record.id,
@@ -57,9 +144,11 @@ function toInfo(record: ReminderRecord): ReminderInfo {
     scheduleKind: record.scheduleKind,
     scheduleValue: record.scheduleValue,
     prompt: record.prompt,
+    handler: record.handler,
+    args: record.args,
     untilPrompt: record.untilPrompt,
     busyPolicy: record.busyPolicy,
-    status: record.status,
+    status: record.status === "firing" ? "armed" : record.status,
     disarmReason: record.disarmReason,
     fireCount: record.fireCount,
     nextFireAt: new Date(record.nextFireAtMs).toISOString(),
@@ -96,17 +185,36 @@ function buildFirePrompt(record: ReminderRecord): string {
 export class ReminderRunner {
   private readonly records = new Map<string, ReminderRecord>();
   private readonly handlers = new Map<string, LiveHandlers>();
+  private readonly namedHandlers = new Map<string, ReminderDefinition>();
+  private readonly namedHandlerNames = new Map<ReminderDefinition, string>();
   private readonly timers = new Map<string, NodeJS.Timeout>();
   private readonly firing = new Set<string>();
   /** Single-flight idle gates keyed by `channelId:continuationToken`. */
   private readonly idleGates = new Map<string, Promise<void>>();
   private started = false;
+  private readonly rejectAnonymousHandlers: boolean;
+  private readonly controlPlane: ReminderControlPlane | undefined;
+  private readonly architecture: "v1" | "v2" | undefined;
 
   constructor(
     private readonly engine: SessionEngine,
     private readonly logger: (line: string) => void = () => {},
-    private readonly platformTimers?: PlatformTimers
-  ) {}
+    private readonly platformTimers?: PlatformTimers,
+    options: ReminderRunnerOptions = {}
+  ) {
+    this.rejectAnonymousHandlers = options.rejectAnonymousHandlers === true;
+    this.controlPlane = options.controlPlane;
+    this.architecture = options.architecture;
+    for (const reminder of options.namedHandlers ?? []) {
+      this.namedHandlers.set(reminder.name, reminder.definition);
+      this.namedHandlerNames.set(reminder.definition, reminder.name);
+    }
+  }
+
+  /** True when create/cancel/rekey/fire go through the CP protocol. */
+  private get usesControlPlaneProtocol(): boolean {
+    return this.controlPlane !== undefined && this.architecture === "v2";
+  }
 
   /**
    * Load reminder documents from the control plane into memory. Does not
@@ -136,6 +244,13 @@ export class ReminderRunner {
       if (record.status !== "armed") {
         continue;
       }
+      if (record.handler !== undefined) {
+        if (this.namedHandlers.get(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          disarmedOrphan += 1;
+        }
+        continue;
+      }
       if (
         (record.hasRunHandler === true || record.hasUntilFn === true) &&
         this.handlers.get(record.id) === undefined
@@ -168,6 +283,16 @@ export class ReminderRunner {
     let restored = 0;
     let disarmedOrphan = 0;
     for (const record of armed) {
+      if (record.handler !== undefined) {
+        if (this.namedHandlers.get(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          disarmedOrphan += 1;
+          continue;
+        }
+        this.armTimer(record);
+        restored += 1;
+        continue;
+      }
       if (
         (record.hasRunHandler === true || record.hasUntilFn === true) &&
         this.handlers.get(record.id) === undefined
@@ -249,9 +374,11 @@ export class ReminderRunner {
   async create(input: ReminderCreateInput): Promise<ReminderInfo> {
     const hasPrompt = input.prompt !== undefined;
     const hasRun = input.run !== undefined;
-    if (hasPrompt === hasRun) {
+    const hasHandler = input.handler !== undefined;
+    const formCount = [hasPrompt, hasRun, hasHandler].filter(Boolean).length;
+    if (formCount !== 1) {
       throw new ReminderValidationError(
-        "reminders.create requires exactly one of prompt or run"
+        "reminders.create requires exactly one of prompt, handler, or run"
       );
     }
     if (input.continuationToken.trim() === "") {
@@ -264,46 +391,136 @@ export class ReminderRunner {
       throw new ReminderValidationError("purpose is required");
     }
 
-    const schedule = resolveSchedule(input);
-    const busyPolicy: ReminderBusyPolicy =
-      input.busyPolicy ?? defaultBusyPolicy(schedule.kind);
-    const now = new Date().toISOString();
-    const id = newReminderId();
-
     const untilPrompt =
       typeof input.until === "string" ? input.until : undefined;
     const untilFn = typeof input.until === "function" ? input.until : undefined;
+
+    if (hasHandler && input.until !== undefined) {
+      throw new ReminderValidationError(
+        "reminders.create: until is not valid with handler; encode the stop condition in args and the handler body"
+      );
+    }
+
+    if (this.rejectAnonymousHandlers) {
+      if (hasRun) {
+        throw new ReminderValidationError(
+          "reminders.create: anonymous run handlers are not durable on architecture v2; author agent/reminders/<name>.ts and pass handler + args"
+        );
+      }
+      if (untilFn !== undefined) {
+        throw new ReminderValidationError(
+          "reminders.create: function until is not durable on architecture v2; use a string until prompt"
+        );
+      }
+    }
+
+    let handlerName: string | undefined;
+    let handlerArgs: JsonObject | undefined;
+    if (hasHandler) {
+      const handler = input.handler!;
+      const name =
+        typeof handler === "string"
+          ? handler.trim()
+          : this.namedHandlerNames.get(handler);
+      if (name === undefined) {
+        throw new ReminderValidationError(
+          "Unknown reminder handler definition (expected a default export discovered under agent/reminders/)"
+        );
+      }
+      if (name === "") {
+        throw new ReminderValidationError("handler name is required");
+      }
+      if (!isValidReminderHandlerName(name)) {
+        throw new ReminderValidationError(
+          name.includes("__")
+            ? `Invalid reminder handler name "${name}": may not contain "__"`
+            : `Invalid reminder handler name "${name}": must match ${NAME_PATTERN}`
+        );
+      }
+      if (this.namedHandlers.get(name) === undefined) {
+        throw new ReminderValidationError(
+          `Unknown reminder handler "${name}" (expected agent/reminders/${name}.ts)`
+        );
+      }
+      if (input.args !== undefined && !isJsonObject(input.args)) {
+        throw new ReminderValidationError(
+          "reminders.create args must be a JSON object"
+        );
+      }
+      handlerName = name;
+      handlerArgs = input.args ?? {};
+      assertReminderArgsSize(handlerArgs);
+    } else if (input.args !== undefined) {
+      throw new ReminderValidationError(
+        "reminders.create args is only valid with handler"
+      );
+    }
+
+    const schedule = resolveSchedule(input);
+    const busyPolicy: ReminderBusyPolicy =
+      input.busyPolicy ?? defaultBusyPolicy(schedule.kind);
     const hasRunHandler = input.run !== undefined;
     const hasUntilFn = untilFn !== undefined;
 
-    const record: ReminderRecord = {
-      version: 1,
-      id,
-      purpose: input.purpose,
-      channelId: input.channelId,
-      continuationToken: input.continuationToken,
-      target: input.target,
-      scheduleKind: schedule.kind,
-      scheduleValue: schedule.value,
-      intervalMs: schedule.intervalMs,
-      prompt: input.prompt,
-      hasRunHandler,
-      hasUntilFn,
-      untilPrompt,
-      busyPolicy,
-      status: "armed",
-      fireCount: 0,
-      nextFireAtMs: schedule.nextFireAtMs,
-      createdAt: now,
-      updatedAt: now,
-    };
+    let record: ReminderRecord;
+    if (this.usesControlPlaneProtocol) {
+      const intent: ReminderCreateIntent = {
+        protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+        purpose: input.purpose,
+        channelId: input.channelId,
+        continuationToken: input.continuationToken,
+        target: input.target,
+        // CP recalculates nextFireAtMs / intervalMs from the raw schedule.
+        schedule: scheduleSpecFromCreateInput(input),
+        prompt: input.prompt,
+        handler: handlerName,
+        args: handlerArgs,
+        hasRunHandler,
+        hasUntilFn,
+        untilPrompt,
+        busyPolicy,
+      };
+      record = await this.controlPlane!.createReminder(intent);
+      this.records.set(record.id, record);
+    } else {
+      const now = new Date().toISOString();
+      const id = newReminderId();
+      record = {
+        version: 1,
+        id,
+        purpose: input.purpose,
+        channelId: input.channelId,
+        continuationToken: input.continuationToken,
+        target: input.target,
+        scheduleKind: schedule.kind,
+        scheduleValue: schedule.value,
+        intervalMs: schedule.intervalMs,
+        prompt: input.prompt,
+        handler: handlerName,
+        args: handlerArgs,
+        hasRunHandler,
+        hasUntilFn,
+        untilPrompt,
+        busyPolicy,
+        status: "armed",
+        fireCount: 0,
+        nextFireAtMs: schedule.nextFireAtMs,
+        generation: 0,
+        createdAt: now,
+        updatedAt: now,
+      };
+      await this.persist(record);
+    }
 
-    await this.persist(record);
-    this.handlers.set(id, {
+    this.handlers.set(record.id, {
       run: input.run,
       untilFn,
     });
-    if (this.started && this.platformTimers === undefined) {
+    if (
+      this.started &&
+      this.platformTimers === undefined &&
+      !this.usesControlPlaneProtocol
+    ) {
       this.armTimer(record);
     }
 
@@ -311,15 +528,18 @@ export class ReminderRunner {
   }
 
   async list(filter?: {
-    status?: ReminderRecord["status"];
+    status?: ReminderStatus;
     purpose?: string;
     continuationToken?: string;
   }): Promise<ReminderInfo[]> {
     const all = await this.allRecords();
     return all
       .filter((r) => {
-        if (filter?.status !== undefined && r.status !== filter.status) {
-          return false;
+        if (filter?.status !== undefined) {
+          const publicStatus = r.status === "firing" ? "armed" : r.status;
+          if (publicStatus !== filter.status) {
+            return false;
+          }
         }
         if (filter?.purpose !== undefined && r.purpose !== filter.purpose) {
           return false;
@@ -348,11 +568,22 @@ export class ReminderRunner {
     id: string,
     reason = "explicit_cancel"
   ): Promise<ReminderInfo | undefined> {
+    if (this.usesControlPlaneProtocol) {
+      const updated = await this.controlPlane!.cancelReminder(id, reason);
+      if (updated === undefined) {
+        this.records.delete(id);
+        this.handlers.delete(id);
+        return undefined;
+      }
+      this.records.set(id, updated);
+      this.handlers.delete(id);
+      return toInfo(updated);
+    }
     const record = await this.getRecord(id);
     if (record === undefined) {
       return undefined;
     }
-    if (record.status !== "armed") {
+    if (record.status !== "armed" && record.status !== "firing") {
       return toInfo(record);
     }
     this.clearTimer(id);
@@ -360,6 +591,7 @@ export class ReminderRunner {
       ...record,
       status: "cancelled",
       disarmReason: reason,
+      generation: (record.generation ?? 0) + 1,
       updatedAt: new Date().toISOString(),
     };
     await this.persist(updated);
@@ -394,7 +626,12 @@ export class ReminderRunner {
     oldToken: string,
     newToken: string
   ): Promise<number> {
-    const armed = (await this.allRecords()).filter((r) => r.status === "armed");
+    if (this.usesControlPlaneProtocol) {
+      return this.controlPlane!.rekeyReminders(channelId, oldToken, newToken);
+    }
+    const armed = (await this.allRecords()).filter(
+      (r) => r.status === "armed" || r.status === "firing"
+    );
     let n = 0;
     for (const record of armed) {
       if (
@@ -406,6 +643,7 @@ export class ReminderRunner {
       await this.persist({
         ...record,
         continuationToken: newToken,
+        generation: (record.generation ?? 0) + 1,
         updatedAt: new Date().toISOString(),
       });
       n += 1;
@@ -441,6 +679,121 @@ export class ReminderRunner {
     return { reminderId, ...result };
   }
 
+  /**
+   * Architecture v2 / CP protocol guest entrypoint: execute an immutable fire
+   * descriptor and return an outcome. Does not mint ids or mutate
+   * authoritative status/fireCount — the control plane applies the outcome.
+   */
+  async executeFire(
+    descriptor: ReminderFireDescriptor
+  ): Promise<ReminderExecutionOutcome> {
+    const record = this.recordFromDescriptor(descriptor);
+    this.records.set(record.id, record);
+
+    const live = this.handlers.get(record.id) ?? {};
+    if (record.handler !== undefined) {
+      if (this.resolveNamedHandler(record.handler) === undefined) {
+        return { kind: "stop", reason: "handler_missing" };
+      }
+    } else if (
+      (record.hasRunHandler === true || record.hasUntilFn === true) &&
+      live.run === undefined &&
+      live.untilFn === undefined
+    ) {
+      return { kind: "stop", reason: "handler_lost_on_restart" };
+    }
+
+    if (live.untilFn !== undefined) {
+      try {
+        const done = await live.untilFn(this.buildUntilContext(record));
+        if (done) {
+          return { kind: "stop", reason: "until_fn" };
+        }
+      } catch (error) {
+        this.logger(
+          `[agent-sdk] reminder "${record.id}" until() failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+    }
+
+    if (await this.isSessionBusy(record.channelId, record.continuationToken)) {
+      if (record.busyPolicy === "skipIfBusy") {
+        this.logger(
+          `[agent-sdk] reminder "${record.id}" (${record.purpose}) skipped: session busy`
+        );
+        return { kind: "skipped" };
+      }
+      await this.whenSessionIdle(record.channelId, record.continuationToken);
+    }
+
+    let result: ReminderFireResult;
+    if (record.handler !== undefined) {
+      const named = this.resolveNamedHandler(record.handler);
+      if (named === undefined) {
+        return { kind: "stop", reason: "handler_missing" };
+      }
+      result = await named.run(this.buildFireContext(record));
+    } else if (live.run !== undefined) {
+      result = await live.run(this.buildFireContext(record));
+    } else if (record.prompt !== undefined) {
+      result = await this.deliverPrompt(record);
+    } else {
+      return { kind: "stop", reason: "missing_handler" };
+    }
+
+    if (result.action === "stop") {
+      return { kind: "stop", reason: "run_stop" };
+    }
+    if (result.action === "skip") {
+      return {
+        kind: "skipped",
+        reschedule:
+          result.reschedule !== undefined
+            ? toWireReschedule(result.reschedule)
+            : undefined,
+      };
+    }
+    return {
+      kind: "delivered",
+      reschedule:
+        result.reschedule !== undefined
+          ? toWireReschedule(result.reschedule)
+          : undefined,
+    };
+  }
+
+  private recordFromDescriptor(
+    descriptor: ReminderFireDescriptor
+  ): ReminderRecord {
+    const now = new Date().toISOString();
+    return {
+      version: 1,
+      id: descriptor.id,
+      purpose: descriptor.purpose,
+      channelId: descriptor.channelId,
+      continuationToken: descriptor.continuationToken,
+      target: descriptor.target,
+      scheduleKind: descriptor.scheduleKind,
+      scheduleValue: descriptor.scheduleValue,
+      intervalMs: descriptor.intervalMs,
+      prompt: descriptor.prompt,
+      handler: descriptor.handler,
+      args: descriptor.args,
+      hasRunHandler: descriptor.hasRunHandler,
+      hasUntilFn: descriptor.hasUntilFn,
+      untilPrompt: descriptor.untilPrompt,
+      busyPolicy: descriptor.busyPolicy,
+      status: "firing",
+      fireCount: descriptor.fireCount,
+      nextFireAtMs: descriptor.nextFireAtMs,
+      generation: descriptor.generation,
+      createdAt: now,
+      updatedAt: now,
+    };
+  }
+
   private armTimer(record: ReminderRecord): void {
     this.clearTimer(record.id);
     if (!this.started || record.status !== "armed") return;
@@ -493,6 +846,10 @@ export class ReminderRunner {
     }
   }
 
+  private resolveNamedHandler(name: string): ReminderDefinition | undefined {
+    return this.namedHandlers.get(name);
+  }
+
   private async fire(
     id: string,
     opts: { force?: boolean } = {}
@@ -515,7 +872,12 @@ export class ReminderRunner {
       }
 
       const live = this.handlers.get(id) ?? {};
-      if (
+      if (record.handler !== undefined) {
+        if (this.resolveNamedHandler(record.handler) === undefined) {
+          await this.disarm(record, "handler_missing");
+          return { outcome: "noop", reason: "handler_missing" };
+        }
+      } else if (
         (record.hasRunHandler === true || record.hasUntilFn === true) &&
         live.run === undefined &&
         live.untilFn === undefined
@@ -560,9 +922,15 @@ export class ReminderRunner {
       }
 
       let result: ReminderFireResult;
-      if (live.run !== undefined) {
-        const fireCtx = this.buildFireContext(record);
-        result = await live.run(fireCtx);
+      if (record.handler !== undefined) {
+        const named = this.resolveNamedHandler(record.handler);
+        if (named === undefined) {
+          await this.disarm(record, "handler_missing");
+          return { outcome: "noop", reason: "handler_missing" };
+        }
+        result = await named.run(this.buildFireContext(record));
+      } else if (live.run !== undefined) {
+        result = await live.run(this.buildFireContext(record));
       } else if (record.prompt !== undefined) {
         result = await this.deliverPrompt(record);
       } else {
@@ -595,7 +963,7 @@ export class ReminderRunner {
         return { outcome: "fired", reason: "skipped" };
       }
       await this.afterFire(latest, "delivered", result.reschedule);
-      this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) delivered`);
+      this.logger(`[agent-sdk] reminder "${id}" (${record.purpose}) fired`);
       return { outcome: "fired", reason: "delivered" };
     } finally {
       this.firing.delete(id);
@@ -662,7 +1030,11 @@ export class ReminderRunner {
       record.continuationToken
     );
     if (auth === undefined) {
-      await this.disarm(record, "session_gone");
+      // Under CP protocol, return stop and let the CP apply/CAS; do not
+      // mutate authoritative status from the guest mid-fire.
+      if (!this.usesControlPlaneProtocol) {
+        await this.disarm(record, "session_gone");
+      }
       return { action: "stop" };
     }
     return this.sendFollowup(record, buildFirePrompt(record), auth);
@@ -721,6 +1093,7 @@ export class ReminderRunner {
         continuationToken: record.continuationToken,
         ...(record.target ?? {}),
       },
+      args: record.args ?? {},
       host: this.engine.host,
       mcp: this.engine.host.mcp,
       appAuth: APP_AUTH,