@cursor/july 0.1.113 → 0.1.114

package/dist/docs/reference/schedules.md

@@ -1,6 +1,6 @@
 # Schedules and reminders
 
-Two ways an agent acts without an inbound message. A schedule is
+An agent can act without an inbound message in two ways. A schedule is
 deploy-time cron: "every weekday at 09:00, summarize open incidents." A
 reminder is a runtime wake bound to one conversation: "re-check this
 PR's CI in two hours." Schedules live in the filesystem; reminders are
@@ -11,10 +11,9 @@ created by running code.
 Cron expressions are standard 5-field, evaluated in UTC with minute
 granularity.
 
-### Schedules in Markdown
+### Markdown schedules
 
-A plain markdown file with `cron:` frontmatter is a fire-and-forget
-task:
+A markdown file with `cron:` frontmatter is a fire-and-forget task:
 
 ```md
 ---
@@ -28,10 +27,10 @@ Each firing starts a task-mode session: the body is the prompt, the
 session runs to `session.completed` or `session.failed`, and it isn't
 followable.
 
-### Schedules as handlers
+### Schedule handlers
 
-`defineSchedule` with a `run` handler gives you full control, most
-usefully to hand the work into a channel so its delivery events fire:
+Use `defineSchedule` with a `run` handler to call tools or hand work into
+a channel so its delivery events fire:
 
 ```ts
 import { defineSchedule } from "@cursor/july/schedules";
@@ -40,7 +39,6 @@ import webhook from "../channels/webhook.js";
 export default defineSchedule({
   cron: "*/30 * * * *",
   async run({ receive, waitUntil, appAuth, host }) {
-    // optional: await host.mcp.callTool("units", "celsius_to_fahrenheit", { value: 0 });
     waitUntil(
       receive(webhook, {
         message:
@@ -59,14 +57,12 @@ schedule-scoped principal for work the agent does on its own behalf),
 and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
 `host.reminders`).
 
-### Dispatch and dev mode
+### Dispatch a schedule
 
-In production (`agent-sdk serve`), schedules fire on their cron
-cadence. Disable them with `--no-schedules`. There's no cross-host
-coordination, so run them in exactly one process per project.
-
-In dev (`serve --dev`), schedules never fire automatically. Dispatch one
-by hand, exactly once, through the same path production uses:
+| Mode | What fires |
+| --- | --- |
+| Production `agent-sdk serve` | Cron cadence. `--no-schedules` disables them. Run them in exactly one process per project |
+| `serve --dev` | Nothing automatic. Dispatch by hand through the same path production uses |
 
 ```bash
 curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
@@ -78,104 +74,67 @@ The playground can dispatch schedules in dev mode too, and
 
 ## Reminders
 
-A reminder is created at runtime and bound to a channel continuation.
-When it fires, it wakes that conversation. Recurring reminders behave
-like `setInterval`, one-shots like `setTimeout`, and both are durable on
-disk.
+A reminder is created at runtime and bound to a channel continuation. A
+prompt reminder wakes that conversation when it fires; a handler reminder
+runs host code, which can call `followup` to wake it. Recurring reminders
+behave like `setInterval`, and one-shots behave like `setTimeout`. Prompt
+and named-handler reminders stay armed across restarts.
 
 ```ts
 await handle.createReminder({
   purpose: "ci_recheck",
   channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  delay: "2h", // or a cron / explicit schedule
+  continuationToken: "pr:acme/checkout#42",
+  delay: "2h",
   prompt: "Re-check CI. Only act if still failing.",
   until: "Cancel once CI is green or the PR is merged.",
 });
 ```
 
-Use `run` when host code should decide what happens on each tick:
+When host code must decide what happens on each tick, author a named
+handler and pass its default export with serializable `args`:
 
 ```ts
-await handle.createReminder({
-  purpose: "ci_recheck",
-  channelId: "drive",
-  continuationToken: "pr:owner/repo#1",
-  every: "30m",
-  async run({ fireCount, followup }) {
-    if (fireCount >= 3) {
-      return { action: "stop" };
-    }
+// agent/reminders/ci_recheck.ts
+import { defineReminder } from "@cursor/july/reminders";
 
+export default defineReminder({
+  async run({ args, followup }) {
     await followup({
-      message: "Re-check CI and report only if the status changed.",
+      message: `Re-check CI for ${String(args.prUrl)}. Report only if the status changed.`,
     });
     return { action: "delivered" };
   },
 });
 ```
 
-This reminder wakes the conversation three times, then stops itself.
-
-The same API is `host.reminders` on channel handlers, tools, and
-schedule runs. An agent can even be given a tool that creates its own
-reminders.
-
-For example, create `agent/tools/remind_me.ts`:
-
 ```ts
-import { defineTool } from "@cursor/july/tools";
-import { z } from "zod";
-
-export default defineTool({
-  description: "Schedule a one-time reminder in this conversation.",
-  inputSchema: z.object({
-    delay: z
-      .string()
-      .describe("When to wake the conversation, such as 20m or 2h"),
-    prompt: z
-      .string()
-      .min(1)
-      .describe("What the agent should do when it wakes"),
-  }),
-  async execute({ delay, prompt }, ctx) {
-    const reminders = ctx.host.reminders;
-    if (reminders === undefined) {
-      throw new Error("Reminders are disabled on this host.");
-    }
-
-    const continuationToken = ctx.session.continuationKey;
-    if (continuationToken == null) {
-      throw new Error("This session cannot receive reminder follow-ups.");
-    }
-
-    const reminder = await reminders.create({
-      purpose: "user_follow_up",
-      channelId: ctx.session.channelId,
-      continuationToken,
-      delay,
-      prompt,
-    });
+import ciRecheck from "./agent/reminders/ci_recheck.js";
 
-    return {
-      reminderId: reminder.id,
-      nextFireAt: reminder.nextFireAt,
-    };
-  },
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:acme/checkout#42",
+  every: "30m",
+  handler: ciRecheck,
+  args: { prUrl: "https://github.com/acme/checkout/pull/42" },
 });
 ```
 
-The tool binds the reminder to the current channel conversation. When
-the delay expires, the prompt returns to the same session as a follow-up.
+Use an anonymous `run` handler only for legacy projects that can re-arm
+it after a restart. New projects should use a named handler.
 
-Reminders fire in one of two styles. The **prompt form** (above) sends
-`prompt` into the session, with `until` stating the standing
-cancellation condition for the model to honor. The **run form** passes a
-`run` handler instead: it returns `stop`, `skip`, or `delivered` per
-tick. That's silent host-side policy with no model turn. Run handlers are
-in-memory, so after a restart those reminders are disarmed
-(`handler_lost_on_restart`); re-arm them from the code path that created
-them, or prefer the prompt form.
+| Form | What it does | After a restart |
+| --- | --- | --- |
+| Prompt | Sends `prompt` into the session. `until` is the standing cancellation condition for the model | Stays armed |
+| Named handler | Runs a discovered handler with serializable `args`; it starts a model turn only if the handler calls `followup` | Stays armed |
+| Anonymous `run` | Host handler returns `stop`, `skip`, or `delivered` per tick; it starts a model turn only if it calls `followup` | Must be re-armed |
+
+The same API is `host.reminders` on channel handlers, tools, and
+schedule runs. `builtinTools: { reminders: true }` adds
+`reminders_create`, `reminders_list`, and `reminders_cancel` on the
+current conversation; see
+[Agent config: built-in tools](/docs/reference/agent-config.md#built-in-tools).
 
 `--dev` does not auto-fire reminders. Dispatch one by hand:
 
@@ -186,27 +145,21 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id>  # fire one
 
 `handle.dispatchReminder(id)` is the programmatic equivalent.
 
-Two habits worth copying: cancel reminders when their subject
-dies (say, cancel PR-scoped reminders on `pull_request.closed`), and keep
-wake prompts generic. A plain "re-check the PR" works better than
-replaying stale payload details, because the agent re-reads the live
-state when it wakes.
+Cancel reminders when their subject dies, for example on
+`pull_request.closed`. Keep wake prompts generic so the agent re-reads
+live state instead of replaying a stale payload.
 
-## Schedule or reminder?
-
-The split comes down to scope and timing.
+## Schedules vs reminders
 
 |          | Schedule                                                   | Reminder                                        |
 | -------- | ---------------------------------------------------------- | ----------------------------------------------- |
 | Defined  | at deploy time, `agent/schedules/*`                        | at runtime, `createReminder` / `host.reminders` |
 | Scope    | global to the agent                                        | one channel continuation (one conversation)     |
 | Session  | starts a new task session (or hands off through `receive`) | wakes an existing conversation                  |
-| Cadence  | cron (UTC)                                                 | delay, cron, or explicit schedule               |
+| Cadence  | cron (UTC)                                                 | `every`, `cron`, `delay`, or `at`                |
 | Dev mode | manual dispatch only                                       | manual dispatch only (timers off)               |
 
-## What's next
-
-Continue with these pages:
+## Related
 
 - [Channels](/docs/reference/channels.md): `receive` and the delivery events
 - [GitHub guide](/docs/guides/github.md): reminders in a real webhook loop