@cursor/july 0.1.105 → 0.1.107

package/src/reminders.ts

@@ -1,30 +1,48 @@
 /**
- * Runtime reminders — per-session durable wakes.
+ * Runtime reminders — per-session durable wakes — and named handlers
+ * authored at `agent/reminders/<name>.ts`.
  *
  * ```ts
+ * import { defineReminder } from "@cursor/july/reminders";
  * import type { ReminderCreateInput } from "@cursor/july/reminders";
  *
+ * // agent/reminders/verdict_recheck.ts
+ * export default defineReminder({
+ *   async run({ args, followup }) {
+ *     await followup({ message: `Recheck ${String(args.headSha)}` });
+ *     return { action: "delivered" };
+ *   },
+ * });
+ *
+ * import verdictRecheck from "./reminders/verdict_recheck.js";
+ *
  * // Recurring ≈ setInterval; one-shot ≈ setTimeout.
  * await host.reminders?.create({
  *   purpose: "ci_recheck",
  *   channelId: session.channelId,
  *   continuationToken: session.continuationKey!,
  *   delay: "2h",
- *   prompt: "Re-check CI. Only act if still failing.",
+ *   handler: verdictRecheck,
+ *   args: { headSha: "abc" },
  * });
  * ```
  *
  * Distinct from `defineSchedule` (deploy-time global cron under
  * `agent/schedules/`). Reminders are created at runtime and bound to a
- * channel continuation. Prefer `run` + function `until` for host policy
- * (silent ticks); agents use prompt-form create via tools.
+ * channel continuation. Prefer named `handler` + serializable `args` for
+ * hosted v2 durability; anonymous `run` remains on local and hosted v1.
  */
 
+import { brandDefinition } from "./internal/brand.js";
+import type { ReminderDefinition, ReminderHandlerConfig } from "./types.js";
+
 export type {
   ReminderBusyPolicy,
   ReminderCreateInput,
+  ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderHandlerConfig,
   ReminderHostApi,
   ReminderInfo,
   ReminderReschedule,
@@ -33,3 +51,16 @@ export type {
   ReminderTarget,
   ReminderUntilContext,
 } from "./types.js";
+
+/**
+ * Brand a named reminder handler for `agent/reminders/<name>.ts`.
+ * The registry name is the module stem (not a field on the definition).
+ */
+export function defineReminder(
+  config: ReminderHandlerConfig
+): ReminderDefinition {
+  if (typeof config.run !== "function") {
+    throw new Error("defineReminder requires a `run` function");
+  }
+  return brandDefinition("reminder", config);
+}

package/src/types.ts

@@ -281,20 +281,8 @@ export interface AgentConfig {
    */
   tools?: ToolName[];
   /**
-   * Hosted architecture this agent deploys onto. Omit or `"v1"` keeps the
-   * current control plane and engine-minted conversation keys. `"v2"`
-   * deploys onto the v2 control plane (v2 APIs and schemas). Omitted
-   * channel `continuation` then inherits from declared events (`github.pr/v2`,
-   * `github.issue/v2`, `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
-   * `deployments.deployment/v2`, `change_monitors.checkpoint/v2`,
-   * `issues.issue/v2`, `none/v2`). An explicit per-channel selector
-   * still overrides.
-   *
-   * ```ts
-   * export default defineAgent({
-   *   architecture: "v2",
-   * });
-   * ```
+   * Hosted architecture override. Leave this unset unless Cursor instructs
+   * you to select a specific architecture.
    */
   architecture?: AgentArchitecture;
 }
@@ -2437,6 +2425,13 @@ export type ChannelEventHandlers<TState = JsonValue> = {
 /** Bound helpers passed to {@link ChannelConfig.onStart}. */
 export interface ChannelStartArgs {
   send: SendMessageFn;
+  /**
+   * Hosted architecture from {@link AgentConfig.architecture}. Omitted
+   * means v1. Host pipelines that call `send()` themselves (instead of
+   * letting the channel adapter stamp continuation) branch on this so
+   * v1 `continuationToken` and v2 `claim` stay mutually exclusive.
+   */
+  architecture?: AgentArchitecture;
   getSession(sessionId: string): Promise<ChannelSession | null>;
   receive(
     channel: ChannelDefinition | HttpChannelDefinition | string,
@@ -2607,9 +2602,8 @@ export interface HttpChannelConfig {
   /** Route auth chain. Defaults to `[localDevStrict()]`. */
   auth?: AuthPolicy[];
   /**
-   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
-   * `"none/v1"` unless the agent set `architecture: "v2"` (then `"none/v2"`
-   * → `evt:`). Override with an explicit `"none/v1"` or `"none/v2"`.
+   * Continuation selector. Omit this to inherit the agent architecture's
+   * default. Set it explicitly only when migrating persisted identities.
    */
   continuation?: ContinuationIdentity;
   /**
@@ -2843,12 +2837,39 @@ export interface ScheduleConfig {
 
 export type ScheduleDefinition = ScheduleConfig & BrandedDefinition<"schedule">;
 
+// ============================================================================
+// Reminder handlers (agent/reminders/*) — named durable fire policies
+// ============================================================================
+
+/**
+ * Authored at `agent/reminders/<name>.ts`. The registry name is the module
+ * stem. Pass the discovered definition to {@link ReminderCreateInput.handler}
+ * with serializable {@link ReminderCreateInput.args}; the engine persists the
+ * stem, not the function.
+ */
+export interface ReminderHandlerConfig {
+  /**
+   * Invoked on every fire with {@link ReminderFireContext} (including the
+   * create-time {@link ReminderFireContext.args} blob).
+   */
+  run: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
+}
+
+export type ReminderDefinition = ReminderHandlerConfig &
+  BrandedDefinition<"reminder">;
+
+export interface DiscoveredReminder {
+  name: string;
+  definition: ReminderDefinition;
+}
+
 // ============================================================================
 // Reminders (runtime per-session wakes)
 // ============================================================================
 
 export type ReminderBusyPolicy = "skipIfBusy" | "queueBehindTurn";
 
+/** Public reminder status. Internal claim state (`firing`) is not exposed. */
 export type ReminderStatus = "armed" | "completed" | "cancelled" | "disarmed";
 
 export type ReminderScheduleKind = "every" | "cron" | "delay" | "at";
@@ -2880,6 +2901,11 @@ export interface ReminderUntilContext {
 
 export interface ReminderFireContext extends ReminderUntilContext {
   appAuth: AuthContext;
+  /**
+   * Serializable args from {@link ReminderCreateInput.args} when the fire
+   * uses a named {@link ReminderCreateInput.handler}. Empty object otherwise.
+   */
+  args: JsonObject;
   /** Wake the reminder's already-bound session (target is implicit). */
   followup(args: { message: string }): Promise<ChannelSession>;
   cancel(reason?: string): Promise<void>;
@@ -2894,9 +2920,11 @@ export interface ReminderFireContext extends ReminderUntilContext {
 /**
  * Create a durable wake bound to a channel continuation.
  *
- * Exactly one of `prompt` | `run`, and exactly one of
+ * Exactly one of `prompt` | `handler` | `run`, and exactly one of
  * `every` | `cron` | `delay` | `at`. Prompt fires always follow up into the
- * bound session.
+ * bound session. Named `handler` resolves `agent/reminders/<name>.ts` on
+ * every fire (survives restart). Anonymous `run` stays supported on local
+ * and hosted v1; hosted architecture v2 rejects it at create.
  *
  * @example Recurring (host policy)
  * ```ts
@@ -2914,6 +2942,28 @@ export interface ReminderFireContext extends ReminderUntilContext {
  * });
  * ```
  *
+ * @example Named handler (durable across restart / hosted v2)
+ * ```ts
+ * // agent/reminders/verdict_recheck.ts
+ * export default defineReminder({
+ *   async run({ args, followup }) {
+ *     // ...
+ *     return { action: "delivered" };
+ *   },
+ * });
+ *
+ * import verdictRecheck from "./reminders/verdict_recheck.js";
+ *
+ * await host.reminders.create({
+ *   purpose: "verdict_recheck",
+ *   channelId: "origin",
+ *   continuationToken,
+ *   delay: "15m",
+ *   handler: verdictRecheck,
+ *   args: { headSha: "abc" },
+ * });
+ * ```
+ *
  * @example One-shot (agent tool / prompt form)
  * ```ts
  * await host.reminders.create({
@@ -2934,8 +2984,22 @@ export interface ReminderCreateInput {
   continuationToken: string;
   /** Optional opaque metadata (e.g. `{ prUrl }`). */
   target?: Record<string, unknown>;
-  /** Exactly one of prompt or run. */
+  /** Exactly one of prompt, handler, or run. */
   prompt?: string;
+  /**
+   * A definition discovered from `agent/reminders/<name>.ts`, or its stem
+   * for compatibility. Mutually exclusive with `prompt` and `run`. The
+   * definition form avoids coupling callers to a filename string; discovery
+   * resolves it to the stable stem persisted by the control plane. Do not
+   * combine with {@link until}; encode stop conditions in {@link args} and
+   * the handler body.
+   */
+  handler?: ReminderDefinition | string;
+  /**
+   * Serializable args for {@link handler} (UTF-8 JSON capped at 32 KiB).
+   * Only valid with `handler`.
+   */
+  args?: JsonObject;
   run?: (ctx: ReminderFireContext) => Promise<ReminderFireResult>;
   /** Exactly one schedule shape. */
   every?: string;
@@ -2945,6 +3009,9 @@ export interface ReminderCreateInput {
   /**
    * Auto-cancel: function (host evaluates, true → cancel) XOR prompt string
    * (agent-facing stop condition; platform does not interpret it).
+   * Valid with `prompt` (string until) and legacy `run` (function until on
+   * local / hosted v1). Not valid with named `handler`. Function until is
+   * rejected on hosted architecture v2.
    */
   until?: string | ((ctx: ReminderUntilContext) => Promise<boolean>);
   /**
@@ -2962,6 +3029,10 @@ export interface ReminderInfo {
   scheduleKind: ReminderScheduleKind;
   scheduleValue: string;
   prompt?: string;
+  /** Named handler stem when create used `handler`. */
+  handler?: string;
+  /** Serializable args when create used `handler`. */
+  args?: JsonObject;
   untilPrompt?: string;
   busyPolicy: ReminderBusyPolicy;
   status: ReminderStatus;
@@ -3213,6 +3284,8 @@ export interface AgentProject {
   httpChannel: HttpChannelDefinition;
   channels: DiscoveredChannel[];
   schedules: DiscoveredSchedule[];
+  /** Named reminder handlers from `agent/reminders/*` (optional / additive). */
+  reminders?: DiscoveredReminder[];
   hooks: DiscoveredHook[];
   /** Live A/B metric experiments (`defineAB`). */
   abs: DiscoveredAB[];
@@ -3318,6 +3391,8 @@ export interface AgentProjectInfo {
     slackChannelPosts?: readonly string[];
   }>;
   schedules: Array<{ name: string; cron: string; kind: "markdown" | "run" }>;
+  /** Named reminder handlers (`agent/reminders/<name>.ts`) when present. */
+  reminders?: Array<{ name: string }>;
   hooks: string[];
   /** Live A/B experiment names (`defineAB` under `agent/ab`). */
   abs: string[];