@cursor/july 0.1.105 → 0.1.108

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;
 }
@@ -1790,7 +1778,14 @@ export type SessionEventPayload =
       type: "turn.bound";
       data: { requestId: string };
     }
-  | { type: "turn.failed"; data: { message: string } }
+  | {
+      type: "turn.failed";
+      data: {
+        message: string;
+        /** Machine-readable terminal status. Omitted on legacy stored events. */
+        status?: "error" | "cancelled";
+      };
+    }
   | {
       /**
        * A Slack follow-up queued mid-turn reached the running agent: the
@@ -1965,6 +1960,10 @@ export interface TurnOutcome {
   status: "finished" | "error" | "cancelled";
   result?: string;
   errorMessage?: string;
+  /** Stable machine-readable runner code when the failure supplied one. */
+  errorCode?: string;
+  /** Why a cancelled turn stopped, when the engine observed the boundary. */
+  cancellationReason?: "signal" | "runner";
   usage?: TurnUsage;
   /** Cost of {@link usage} from the Cloud Agents cost endpoint. */
   cost?: TurnCost;
@@ -2035,7 +2034,10 @@ export interface ChannelSession {
   getEventStream(options?: {
     startIndex?: number;
   }): Promise<ReadableStream<Uint8Array>>;
-  /** Resolves when the currently running turn reaches a terminal event. */
+  /**
+   * Resolves after the currently running turn reaches a terminal event and
+   * handlers already queued for that session have settled.
+   */
   waitForCompletion(): Promise<TurnOutcome>;
   /** Re-key the session's channel-local continuation token. */
   setContinuationToken(token: string | null): Promise<void>;
@@ -2396,7 +2398,14 @@ export interface ReceiveInput {
   target?: JsonObject;
 }
 
-/** Per-event channel context: live (persisted) state plus session ops. */
+/**
+ * Per-event channel context. `state` is mutable. Turn events receive the
+ * state snapshot captured for that turn; handler mutations are recursively
+ * merged into the latest persisted state so fields refreshed by overlapping
+ * deliveries survive. At paths changed by the handler, objects merge
+ * recursively, arrays and scalars replace the latest value, and deletion
+ * removes the latest value. Events outside a turn receive current live state.
+ */
 export interface ChannelEventContext<TState = JsonValue> {
   channelId: string;
   state: TState;
@@ -2413,6 +2422,11 @@ export interface SessionContext {
    * relative path cannot read another session's files.
    */
   host: HostContext;
+  /**
+   * Durable artifacts bound to this event's session and turn. `tag`
+   * auto-fills both ids and rejects a conflicting explicit `sessionId`.
+   */
+  artifacts: ArtifactsApi;
 }
 
 export type ChannelEventHandler<
@@ -2437,6 +2451,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 +2628,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;
   /**
@@ -2717,6 +2737,8 @@ export type ArtifactsDefinition = ArtifactsConfig &
  */
 export interface ResultContext {
   session: SessionInfo;
+  /** Durable channel state captured for this turn. */
+  channelState: JsonValue;
   host: HostContext;
   artifacts: ArtifactsApi;
   stateRoot: string;
@@ -2843,12 +2865,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 +2929,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 +2948,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 +2970,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 +3012,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 +3037,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 +3057,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 +3312,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 +3419,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[];
@@ -3467,8 +3570,11 @@ export interface ServeOptions {
   stateRoot?: string;
   /**
    * Cursor API key for the SDK runner and Cursor account MCP connections.
-   * When omitted, falls back to `CURSOR_API_KEY`, then to the credential
-   * stored by `agent-sdk login`.
+   * When omitted, falls back to `CURSOR_API_KEY`, then
+   * `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
+   * when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the credential
+   * stored by `agent-sdk login`. A bind file wins over
+   * `CURSOR_SERVICE_ACCOUNT_KEY`.
    */
   apiKey?: string;
   /** Run schedules on their cron cadence. Defaults to `!dev`. */
@@ -3553,7 +3659,9 @@ export interface ServeOptions {
    * GitHub and Origin subscriptions are registered independently.
    * The stream is read as the host's Cursor user, so this requires a signed-in
    * host: `serve` throws when no key resolves from `apiKey` here,
-   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, or `agent-sdk login`.
+   * {@link ServeOptions.apiKey}, `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`
+   * (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset),
+   * `CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
    */
   cursorEvents?: {
     repos: string[];