@cursor/july 0.1.104 → 0.1.107

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;
 }
@@ -1926,8 +1914,9 @@ export interface SessionRecord {
    */
   workspaceOverride?: string;
   /**
-   * One-shot files to write into the harness cwd before the next turn
-   * (see {@link SendMessageOptions.workspaceFiles}). Cleared after apply.
+   * One-shot files for the next turn (see {@link SendMessageOptions.workspaceFiles}).
+   * Local turns write them into the harness cwd. Cloud turns sync them onto
+   * the session Agent Store prefix. Cleared after apply.
    */
   pendingWorkspaceFiles?: Record<
     string,
@@ -2112,12 +2101,12 @@ export interface SendMessageOptions {
    */
   workspaceDir?: string;
   /**
-   * Relative path → contents written into the session harness cwd after
-   * scaffold materialize and before the next turn. On create, queued for
-   * the first turn; on resume, replaces any pending files. Prefer this
-   * over {@link workspaceDir} when you only need to inject a few
-   * host-prepared files (skills/AGENTS.md still land in the normal
-   * session workspace). Values may be utf8 strings or
+   * Relative path → contents for the next turn. Local turns write them into
+   * the harness cwd after scaffold materialize. Cloud turns sync them onto
+   * the session Agent Store prefix instead of the VM working directory. On
+   * create, queued for the first turn; on resume, merged into any pending
+   * files. Prefer this over {@link workspaceDir} when you only need to
+   * inject a few host-prepared files. Values may be utf8 strings or
    * `{ encoding: "base64", data }` blobs (Slack attachments, binary docs).
    */
   workspaceFiles?: Record<
@@ -2436,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,
@@ -2606,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;
   /**
@@ -2842,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";
@@ -2879,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>;
@@ -2893,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
@@ -2913,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({
@@ -2933,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;
@@ -2944,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>);
   /**
@@ -2961,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;
@@ -3212,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[];
@@ -3317,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[];

package/templates/grokbot-agents/README.md

@@ -0,0 +1,26 @@
+# Grok Bot agents
+
+Consults the Grok Bot agents you name. This agent stays in its own
+conversation and reports the reply.
+
+```bash
+npx @cursor/july init ./grokbot --template grokbot-agents
+```
+
+`init` asks for the names shown in the Grok Bot app. Skip the prompt
+with `--var agents="Plan Keeper, Chief of Staff"`.
+
+## Run
+
+```bash
+agent-sdk login
+agent-sdk dev
+```
+
+In the playground, ask it to talk to one of the names you entered. A
+name outside the list is refused.
+
+## Edit
+
+- `agent/extensions/grokbot.ts`: who it may talk to
+- `agent/instructions.md`: when to consult them

package/templates/grokbot-agents/agent/agent.ts

@@ -0,0 +1,6 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  // Empty allowlist: only the mounted Grok Bot tools.
+  tools: [],
+});

package/templates/grokbot-agents/agent/extensions/grokbot.ts

@@ -0,0 +1,5 @@
+import cursorGrokBotAgents from "@cursor/july/extensions/cursor-grokbot-agents";
+
+export default cursorGrokBotAgents({
+  agents: ["Plan Keeper"],
+});

package/templates/grokbot-agents/agent/instructions.md

@@ -0,0 +1,7 @@
+# Grok Bot agents
+
+Consult the Grok Bot agents named in `agent/extensions/grokbot.ts`. Stay in this conversation and report the reply.
+
+When someone asks who you can talk to, call `grokbot__list`. Do not send a message.
+
+When the question belongs to one of those agents, use the consult skill. A name outside the list is refused.

package/templates/grokbot-agents/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/grokbot-agents/evals/grokbot-agents.eval.ts

@@ -0,0 +1,18 @@
+import { defineEval } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "list",
+      description: "Asked who it can talk to, it lists and does not send.",
+      async test(t) {
+        await t.send("Who can you talk to? List them. Do not message anyone.");
+        t.succeeded();
+        t.calledTool("grokbot__list");
+        t.notCalledTool("grokbot__ask");
+        t.notCalledTool("grokbot__interrupt");
+      },
+    },
+  ],
+});

package/templates/grokbot-agents/init.json

@@ -0,0 +1,18 @@
+{
+  "questions": [
+    {
+      "id": "agents",
+      "prompt": "Which Grok Bot agents may this agent talk to?",
+      "hint": "Comma-separated names, as shown in the Grok Bot app.",
+      "placeholder": "Plan Keeper, Chief of Staff"
+    }
+  ],
+  "replace": [
+    {
+      "file": "agent/extensions/grokbot.ts",
+      "find": "[\"Plan Keeper\"]",
+      "answer": "agents",
+      "as": "json-array"
+    }
+  ]
+}

package/templates/grokbot-agents/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "grokbot-agents",
+  "private": true,
+  "type": "module",
+  "description": "Consults the Grok Bot agents you name.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/grokbot-agents/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}