@cursor/july 0.1.105 → 0.1.108

package/src/internal/cursor/backend-client.ts

@@ -82,6 +82,37 @@ const githubTokenResponseSchema: z.ZodType<CursorGithubToken> = z.object({
   expiresAt: z.string().datetime(),
 });
 
+/** SCMs whose git fetches ride the backend's `/v0/scm-events/<provider>-git-proxy` routes. */
+export type CursorScmCloneProvider = "gitlab" | "bitbucket";
+
+/**
+ * Proxied clone target for a GitLab / Bitbucket repository. The backend
+ * never hands out the provider credential: git fetches go to `remoteUrl`
+ * on the backend with the caller's own Cursor API key as a bearer token,
+ * and the backend adds the tenant credential per request.
+ */
+export interface CursorScmCloneTarget {
+  /** Absolute `<backend>/v0/scm-events/<provider>-git-proxy/<repo>.git`. */
+  remoteUrl: string;
+  /** Bearer credential git presents to the backend (the caller's API key). */
+  token: string;
+  /** ISO timestamp after which the caller re-resolves the target. */
+  expiresAt: string;
+  username: string;
+  authMode: "bearer";
+}
+
+const scmCloneTargetResponseSchema = z.object({
+  expiresAt: z.string().datetime(),
+  clone: z.object({
+    remotePath: z
+      .string()
+      .regex(/^\/v0\/scm-events\/[a-z]+-git-proxy\/.+\.git$/),
+    username: z.string().min(1),
+    authMode: z.literal("bearer"),
+  }),
+});
+
 const mcpToolSchema = z.object({
   name: z.string(),
   providerIdentifier: z.string().optional(),
@@ -490,6 +521,62 @@ export class CursorBackendClient {
     return githubTokenResponseSchema.parse(parsed);
   }
 
+  /**
+   * Resolve the proxied clone target for a GitLab / Bitbucket repository
+   * (`owner/name`; GitLab `path_with_namespace`). Same authorization as the
+   * provider proxy this host already calls; the returned remote lives on
+   * the backend and takes this client's API key, never a provider token.
+   */
+  async getScmCloneTarget(
+    provider: CursorScmCloneProvider,
+    repo: string
+  ): Promise<CursorScmCloneTarget> {
+    const label = provider === "gitlab" ? "GitLab" : "Bitbucket";
+    let response: Response;
+    try {
+      response = await this.fetchImpl(
+        `${this.backendUrl}/v0/scm-events/${provider}-clone-target`,
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.currentApiKey()}`,
+          },
+          body: JSON.stringify({ repo }),
+          signal: AbortSignal.timeout(30_000),
+        }
+      );
+    } catch (error) {
+      throw new CursorBackendError(
+        `Cursor ${label} clone target request failed: ${describeError(error)}`
+      );
+    }
+    const text = await response.text();
+    if (!response.ok) {
+      throw new CursorBackendError(
+        describeGithubTokenHttpFailure(response.status, text, label),
+        response.status,
+        retryAfterMsFromResponse(response)
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      throw new CursorBackendError(
+        `Cursor backend returned a non-JSON ${label} clone target response.`
+      );
+    }
+    const body = scmCloneTargetResponseSchema.parse(parsed);
+    return {
+      remoteUrl: `${this.backendUrl}${body.clone.remotePath}`,
+      token: this.currentApiKey(),
+      expiresAt: body.expiresAt,
+      username: body.clone.username,
+      authMode: body.clone.authMode,
+    };
+  }
+
   /**
    * One unary Connect-JSON call on `aiserver.v1.<service>` with the same
    * token exchange and 401 retry as the dashboard RPCs. Callers parse the
@@ -864,7 +951,8 @@ const MAX_GITHUB_TOKEN_RETRY_AFTER_MS = 60 * 60_000;
  */
 function describeGithubTokenHttpFailure(
   status: number,
-  bodyText: string
+  bodyText: string,
+  label = "GitHub"
 ): string {
   const detail = githubTokenErrorFromBody(bodyText);
   if (status === 401) {
@@ -875,7 +963,7 @@ function describeGithubTokenHttpFailure(
   if (detail !== undefined) {
     return detail;
   }
-  return `Cursor GitHub credential request failed (${status}).`;
+  return `Cursor ${label} credential request failed (${status}).`;
 }
 
 function githubTokenErrorFromBody(bodyText: string): string | undefined {

package/src/internal/cursor/credentials.ts

@@ -176,10 +176,15 @@ export async function clearStoredCredentials(): Promise<boolean> {
 }
 
 // ============================================================================
-// Resolution (option > env > file > stored login)
+// Resolution (option > env > file > service account > stored login)
 // ============================================================================
 
-export type ApiKeySource = "option" | "env" | "file" | "login";
+export type ApiKeySource =
+  | "option"
+  | "env"
+  | "file"
+  | "service-account"
+  | "login";
 
 export interface ResolvedApiKey {
   apiKey: string;
@@ -274,10 +279,25 @@ export function consumeBoundCursorApiKey(options?: {
   };
 }
 
+function presentEnvKey(name: string): string | undefined {
+  const value = process.env[name];
+  if (value === undefined) {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
 /**
  * First present source wins. We define the order; operators do not.
  * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`
- * (hosted default path if unset) → stored `july login`.
+ * (hosted default path if unset) → `CURSOR_SERVICE_ACCOUNT_KEY` → stored
+ * `july login`.
+ *
+ * A cloud-agent VM often has the service-account key and no user API key.
+ * The explicit key and the hosted bind file still win, so a task credential
+ * is not replaced by the ambient service-account key. The service-account
+ * key wins over a leftover personal login.
  */
 export function resolveApiKeySync(options?: {
   apiKey?: string;
@@ -287,14 +307,22 @@ export function resolveApiKeySync(options?: {
   if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
     return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
   }
-  const envKey = process.env.CURSOR_API_KEY;
-  if (envKey !== undefined && envKey.trim() !== "") {
-    return { apiKey: envKey.trim(), source: "env", backendUrl };
+  const envKey = presentEnvKey("CURSOR_API_KEY");
+  if (envKey !== undefined) {
+    return { apiKey: envKey, source: "env", backendUrl };
   }
   const fileKey = readApiKeyFromFile();
   if (fileKey !== undefined) {
     return { apiKey: fileKey, source: "file", backendUrl };
   }
+  const serviceAccountKey = presentEnvKey("CURSOR_SERVICE_ACCOUNT_KEY");
+  if (serviceAccountKey !== undefined) {
+    return {
+      apiKey: serviceAccountKey,
+      source: "service-account",
+      backendUrl,
+    };
+  }
   const stored = readStoredCredentialsSync();
   if (stored !== undefined && stored.backendUrl === backendUrl) {
     return { apiKey: stored.apiKey, source: "login", backendUrl };
@@ -313,7 +341,7 @@ export async function resolveApiKey(options?: {
 }
 
 /** One-line hint for "no credentials" errors, shared across surfaces. */
-export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / pass serve({ apiKey })).`;
+export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / CURSOR_SERVICE_ACCOUNT_KEY / pass serve({ apiKey })).`;
 
 // ============================================================================
 // PKCE browser login (mirrors cursor-agent / Sand)

package/src/internal/deploy-client.ts

@@ -285,6 +285,21 @@ export interface AgentkitStopAccepted {
   status: string;
 }
 
+/**
+ * `POST /internal/agentsdk/deployments/:slug/sessions` 202 body. A hosted v2
+ * session start is a Temporal delivery: a fresh start allocates `ses_…`
+ * only after admission (poll the session list), so the ack is the delivery
+ * and workflow ids. `sessionId` is present only when the call resumed one.
+ */
+export interface AgentkitStartSessionAccepted {
+  deliveryId: string;
+  workflowId: string;
+  sessionMode: "event" | "continuation";
+  sessionId?: string;
+  dryRun?: true;
+  asOf?: string;
+}
+
 /** One secret's metadata from the list endpoint — names only, never values. */
 export interface SecretInfo {
   name: string;
@@ -373,6 +388,17 @@ const agentkitStopAcceptedSchema = z
   })
   .passthrough();
 
+const agentkitStartSessionAcceptedSchema = z
+  .object({
+    deliveryId: z.string().min(1),
+    workflowId: z.string().min(1),
+    sessionMode: z.enum(["event", "continuation"]),
+    sessionId: z.string().min(1).optional(),
+    dryRun: z.literal(true).optional(),
+    asOf: z.string().min(1).optional(),
+  })
+  .passthrough();
+
 const deploymentSchema = z.object({
   id: z.number(),
   slug: z.string(),
@@ -675,6 +701,50 @@ export class AgentServeDeployClient {
     return agentkitStopAcceptedSchema.parse(raw);
   }
 
+  /**
+   * Delete a v2 deployment (`DELETE /internal/agentsdk/deployments/:slug`).
+   * 202 means accepted; poll {@link getAgentkitDeploy} until 404.
+   */
+  async deleteAgentkit(args: {
+    teamId: number;
+    slug: string;
+  }): Promise<AgentkitStopAccepted> {
+    const raw = await this.request({
+      method: "DELETE",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}?teamId=${args.teamId}`,
+      context: { verb: "delete", slug: args.slug },
+    });
+    return agentkitStopAcceptedSchema.parse(raw);
+  }
+
+  /**
+   * Start (or, with `sessionId`, resume) a hosted v2 session through the
+   * control plane (`POST /internal/agentsdk/deployments/:slug/sessions`).
+   * Does not talk to the v1 engine alias or `/engine/*`.
+   */
+  async startSession(args: {
+    teamId: number;
+    slug: string;
+    message: string;
+    sessionId?: string;
+    dryRun?: boolean;
+    asOf?: string;
+  }): Promise<AgentkitStartSessionAccepted> {
+    const raw = await this.request({
+      method: "POST",
+      path: `/internal/agentsdk/deployments/${encodeURIComponent(args.slug)}/sessions`,
+      body: {
+        teamId: args.teamId,
+        message: args.message,
+        sessionId: args.sessionId,
+        dryRun: args.dryRun === true ? true : undefined,
+        asOf: args.asOf,
+      },
+      context: { verb: "start session", slug: args.slug },
+    });
+    return agentkitStartSessionAcceptedSchema.parse(raw);
+  }
+
   async listDeployments(args: { teamId: number }): Promise<Deployment[]> {
     const raw = await this.request({
       method: "GET",

package/src/internal/deploy-manifest.ts

@@ -30,7 +30,11 @@
  */
 
 import { z } from "zod";
-import { isPublicEndpointPolicy } from "../channels.js";
+import {
+  type CatchAuthDeclaration,
+  catchAuthDeclaration,
+  isPublicEndpointPolicy,
+} from "../channels.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
@@ -47,7 +51,7 @@ import {
   projectInfo,
   runtimeArchitectureCompatibilityError,
 } from "./discovery.js";
-import { packageVersion } from "./distribution.js";
+import { packageGitSha, packageVersion } from "./distribution.js";
 
 export const DEPLOY_MANIFEST_VERSION: 1 = 1;
 
@@ -58,10 +62,48 @@ export const DEPLOY_MANIFEST_VERSION: 1 = 1;
  */
 const continuationIdentitySchema = z.enum(CONTINUATION_SELECTORS);
 
+const CATCH_MAX_ROUTES = 32;
+const CATCH_MAX_AUTH_POLICIES = 4;
+
+const catchDeclarationSchema = z.object({
+  routes: z
+    .array(
+      z.object({
+        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+        path: z.string().min(1).max(1024),
+      })
+    )
+    .min(1)
+    .max(CATCH_MAX_ROUTES),
+  auth: z
+    .array(
+      z.discriminatedUnion("kind", [
+        z.object({
+          kind: z.literal("header"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+        }),
+        z.object({
+          kind: z.literal("hmac-sha256"),
+          header: z.string().min(1).max(128),
+          secret: z.string().min(1).max(64),
+          prefix: z.string().max(32).optional(),
+        }),
+        z.object({ kind: z.literal("public") }),
+      ])
+    )
+    .min(1)
+    .max(CATCH_MAX_AUTH_POLICIES),
+});
+
 const agentDeployManifestV1Schema = z.object({
   manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
   generatedAtMs: z.number().int().nonnegative(),
   cliVersion: z.string().min(1),
+  cliGitSha: z
+    .string()
+    .regex(/^[0-9a-f]{40,64}$/)
+    .optional(),
   declarations: z.object({
     egressDomains: z.array(z.string().min(1)).max(64),
     publicRoutePaths: z.array(z.string().min(1)).max(64),
@@ -74,6 +116,7 @@ const agentDeployManifestV1Schema = z.object({
           kind: z.string().min(1).max(32).optional(),
           eventTypes: z.array(z.string().min(1).max(64)).max(64).optional(),
           continuation: continuationIdentitySchema,
+          catch: catchDeclarationSchema.optional(),
         })
       )
       .max(64),
@@ -106,7 +149,22 @@ export interface AgentDeployManifestDeclarations {
     kind?: string;
     eventTypes?: string[];
     continuation: ContinuationIdentity;
+    /**
+     * Control-plane catch routes: present only for an authored channel
+     * whose auth chain carries a `sharedSecretAuth` / `hmacSignatureAuth`
+     * policy. The control plane accepts exactly these `(method, path)`
+     * pairs and verifies the named deployment secret before any compute.
+     */
+    catch?: AgentDeployManifestCatchDeclaration;
+  }>;
+}
+
+export interface AgentDeployManifestCatchDeclaration {
+  routes: Array<{
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
   }>;
+  auth: CatchAuthDeclaration[];
 }
 
 export interface AgentDeployManifestV1 {
@@ -115,6 +173,8 @@ export interface AgentDeployManifestV1 {
   generatedAtMs: number;
   /** `@cursor/july` version that produced the manifest. */
   cliVersion: string;
+  /** Git commit for a checkout-built `@cursor/july`; absent for npm builds. */
+  cliGitSha?: string;
   declarations: AgentDeployManifestDeclarations;
   /**
    * Full `projectInfo` payload (see `GET /v1/info`). Opaque to the wire
@@ -129,7 +189,7 @@ export interface AgentDeployManifestV1 {
  */
 export function buildAgentDeployManifest(
   project: AgentProject,
-  options?: { nowMs?: number; cliVersion?: string }
+  options?: { nowMs?: number; cliVersion?: string; cliGitSha?: string }
 ): AgentDeployManifestV1 {
   const runtimeArchitectureError = runtimeArchitectureCompatibilityError(
     project.agent
@@ -152,6 +212,7 @@ export function buildAgentDeployManifest(
       kind,
       eventTypes,
       continuation: channelContinuationIdentity(channel.definition),
+      catch: channelCatchDeclaration(channel.definition),
     };
   });
 
@@ -167,20 +228,19 @@ export function buildAgentDeployManifest(
     manifestVersion: DEPLOY_MANIFEST_VERSION,
     generatedAtMs: options?.nowMs ?? Date.now(),
     cliVersion: options?.cliVersion ?? packageVersion(),
+    cliGitSha: options?.cliGitSha ?? packageGitSha(),
     declarations: {
       egressDomains: [...(project.agent.hosting?.egressDomains ?? [])],
       publicRoutePaths,
-      // v2 ignores authored storage; deploy manifests describe
-      // Cursor-hosted deployments, where framework-storage-selection.ts
-      // injects the Cursor-hosted mirror.
+      // Deploy manifests describe Cursor-hosted deployments. When the agent
+      // authors no storage, framework-storage-selection.ts injects the
+      // platform Cursor-hosted mirror for both v1 and v2.
       frameworkStorage:
-        project.agent.architecture === "v2"
+        project.storage === undefined
           ? "cursor-hosted"
-          : project.storage === undefined
-            ? "none"
-            : isCursorHostedStorage(project.storage)
-              ? "cursor-hosted"
-              : "other",
+          : isCursorHostedStorage(project.storage)
+            ? "cursor-hosted"
+            : "other",
       ...(project.agent.architecture === undefined
         ? {}
         : { architecture: project.agent.architecture }),
@@ -190,6 +250,65 @@ export function buildAgentDeployManifest(
   };
 }
 
+/**
+ * Catch declaration for one authored channel: its routes, gated by the
+ * catch-capable policies in its auth chain (`sharedSecretAuth`,
+ * `hmacSignatureAuth`, or `publicEndpoint()` for handler-verified routes).
+ * A routed channel with none of those declares nothing and is not reachable
+ * through the catch API.
+ */
+export function channelCatchDeclaration(
+  definition: AgentProject["channels"][number]["definition"]
+): AgentDeployManifestCatchDeclaration | undefined {
+  const routes = definition.routes ?? [];
+  if (routes.length === 0) {
+    return undefined;
+  }
+  const declared = (definition.auth ?? [])
+    .map(catchAuthDeclaration)
+    .filter((declaration) => declaration !== undefined);
+  if (declared.length === 0) {
+    return undefined;
+  }
+  // An auth chain is any-of, so `publicEndpoint()` beside secret policies
+  // admits everything locally and on the control plane alike. Declare one
+  // `public` entry (the control plane then decrypts nothing) but keep the
+  // shared-secret header policies next to it: they are what the control
+  // plane uses to strip those header values before the request is
+  // claim-checked, and senders keep sending the secret regardless of
+  // whether anything still checks it. HMAC policies carry body digests,
+  // not secrets, so nothing is lost by dropping them.
+  const isPublic = declared.some((policy) => policy.kind === "public");
+  const auth = isPublic
+    ? [
+        { kind: "public" as const },
+        ...declared.filter((policy) => policy.kind === "header"),
+      ]
+    : declared;
+  if (routes.length > CATCH_MAX_ROUTES) {
+    if (isPublic) {
+      // publicEndpoint() channels deployed before catch existed; they stay
+      // reachable the way they were (not through catch) rather than
+      // failing the deploy.
+      return undefined;
+    }
+    throw new Error(
+      `Catch channels may declare at most ${CATCH_MAX_ROUTES} routes (got ${routes.length}).`
+    );
+  }
+  if (auth.length > CATCH_MAX_AUTH_POLICIES) {
+    throw new Error(
+      isPublic
+        ? `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} auth policies; publicEndpoint() plus ${String(auth.length - 1)} sharedSecretAuth() policies is ${String(auth.length)}. Drop publicEndpoint() or the shared-secret policies it makes dead.`
+        : `Catch channels may declare at most ${CATCH_MAX_AUTH_POLICIES} secret policies (got ${auth.length}).`
+    );
+  }
+  return {
+    routes: routes.map((route) => ({ method: route.method, path: route.path })),
+    auth,
+  };
+}
+
 /**
  * Parse an untrusted manifest (round-trip check for the CLI's own output;
  * the CP re-validates server-side with its own copy of the contract).

package/src/internal/describe-error.ts

@@ -2,3 +2,31 @@
 export function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+export function describeErrorCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const numericCode = (error as { code?: unknown }).code;
+    if (numericCode === 1) {
+      return "canceled";
+    }
+    if (numericCode === 14) {
+      return "unavailable";
+    }
+    if (numericCode === 2) {
+      return "unknown";
+    }
+  }
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    (error as { name?: unknown }).name === "AbortError"
+  ) {
+    return "ABORT_ERR";
+  }
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" && code.length <= 64 ? code : undefined;
+}

package/src/internal/discovery/agent.ts

@@ -372,6 +372,7 @@ export async function warnUnknownSlots(
     "subagents",
     "channels",
     "schedules",
+    "reminders",
     "hooks",
     "ab",
     "sandbox",

package/src/internal/discovery/info.ts

@@ -151,6 +151,12 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
       cron: schedule.cron,
       kind: schedule.kind,
     })),
+    reminders:
+      (project.reminders ?? []).length === 0
+        ? undefined
+        : (project.reminders ?? []).map((reminder) => ({
+            name: reminder.name,
+          })),
     hooks: project.hooks.map((hook) => hook.name),
     abs: project.abs.map((experiment) => experiment.name),
     ...(project.abConfig === undefined && project.abs.length === 0

package/src/internal/discovery/modules.ts

@@ -9,10 +9,7 @@ import { type DiscoveryContext, displayPath, errorMessage } from "./context.js";
 import { isDirectory, isModuleFile, moduleStem, sortedEntries } from "./fs.js";
 import { validateName } from "./names.js";
 
-type ImportableKind = Exclude<
-  DefinitionKind,
-  "instructions" | "eval" | "reminder"
->;
+type ImportableKind = Exclude<DefinitionKind, "instructions" | "eval">;
 
 /** The module files of a slot directory whose filenames are valid names. */
 export async function moduleEntries(
@@ -104,6 +101,7 @@ const DEFINE_HELPER_NAME: Record<ImportableKind, string> = {
   channel: "defineChannel",
   "http-channel": "httpChannel",
   schedule: "defineSchedule",
+  reminder: "defineReminder",
   hook: "defineHook",
   ab: "defineAB",
   storage: "defineStorage",

package/src/internal/discovery/project.ts

@@ -31,6 +31,7 @@ import {
 } from "./fs.js";
 import { loadHooks } from "./hooks.js";
 import { NAME_PATTERN } from "./names.js";
+import { loadReminders } from "./reminders.js";
 import { loadSchedules } from "./schedules.js";
 import {
   appendArtifactTool,
@@ -236,6 +237,7 @@ export async function loadAgentProject(
   }
   const schedules = await loadSchedules(ctx, join(agentDir, "schedules"));
   schedules.push(...projectSlots.schedules);
+  const reminders = await loadReminders(ctx, join(agentDir, "reminders"));
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
   hooks.push(...projectSlots.hooks);
   const abs = await loadABs(ctx, agentDir);
@@ -291,6 +293,7 @@ export async function loadAgentProject(
     httpChannel: resolvedHttpChannel,
     channels,
     schedules,
+    reminders,
     hooks,
     abs,
     abConfig,

package/src/internal/discovery/reminders.ts

@@ -0,0 +1,65 @@
+/**
+ * `agent/reminders/*.ts`: named durable reminder fire handlers.
+ */
+
+import { basename, extname, relative } from "node:path";
+import type { DiscoveredReminder, ReminderDefinition } from "../../types.js";
+import { getDefinitionKind } from "../brand.js";
+import { type DiscoveryContext, displayPath } from "./context.js";
+import { isDirectory, isModuleFile, toPosix, walkFiles } from "./fs.js";
+import { importDefault } from "./modules.js";
+import { NAME_PATTERN } from "./names.js";
+
+export async function loadReminders(
+  ctx: DiscoveryContext,
+  remindersDir: string,
+  onDisable?: (name: string, path: string) => void
+): Promise<DiscoveredReminder[]> {
+  if (!(await isDirectory(remindersDir))) {
+    return [];
+  }
+  const reminders: DiscoveredReminder[] = [];
+  for (const filePath of await walkFiles(remindersDir)) {
+    const rel = toPosix(relative(remindersDir, filePath));
+    if (!isModuleFile(basename(filePath))) {
+      continue;
+    }
+    const name = rel.slice(0, -extname(rel).length);
+    if (!NAME_PATTERN.test(name) || name.includes("__")) {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: name.includes("__")
+          ? `Reminder name "${name}" may not contain "__"; it is reserved for extension contributions (\`<ns>__<name>\`).`
+          : `Reminder name "${name}" must match ${NAME_PATTERN}.`,
+      });
+      continue;
+    }
+    const definition = await importDefault(
+      ctx,
+      filePath,
+      onDisable === undefined ? "reminder" : ["reminder", "disabled"]
+    );
+    if (definition === undefined) {
+      continue;
+    }
+    if (getDefinitionKind(definition) === "disabled") {
+      onDisable?.(name, filePath);
+      continue;
+    }
+    const reminder = definition as ReminderDefinition;
+    if (typeof reminder.run !== "function") {
+      ctx.diagnostics.push({
+        severity: "error",
+        path: displayPath(ctx, filePath),
+        message: "Reminder handlers require a `run` function.",
+      });
+      continue;
+    }
+    reminders.push({
+      name,
+      definition: reminder,
+    });
+  }
+  return reminders;
+}

package/src/internal/discovery/subagent.ts

@@ -121,6 +121,7 @@ async function warnUnsupportedSubagentSlots(
     ["subagents", "nested subagents"],
     ["channels", "channels"],
     ["schedules", "schedules"],
+    ["reminders", "reminders"],
     ["hooks", "hooks"],
     ["sandbox", "sandbox files"],
   ] as const;