@cursor/july 0.1.104 → 0.1.107

package/src/internal/session-engine.ts

@@ -202,13 +202,19 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  buildCloudSessionWorkspaceSection,
   buildCloudWorkspaceSection,
   ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
 } from "./workspace.js";
-import { syncWorkspaceToStore } from "./workspace-sync.js";
+import {
+  syncSessionWorkspaceFiles,
+  syncWorkspaceToStore,
+  WorkspaceFileRefusal,
+  wipeSessionWorkspace,
+} from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
@@ -222,6 +228,7 @@ interface CloudStoreTarget {
   mountPath: string;
   skillsPrefix: string;
   workspacePrefix: string;
+  sessionWorkspacePrefix: (sessionId: string) => string;
   label: string;
 }
 
@@ -2254,10 +2261,13 @@ export class SessionEngine {
         await this.baselineDeliveredNudges(record);
         const pendingFiles = record.pendingWorkspaceFiles;
         const pendingImages = record.pendingImages;
-        if (
-          pendingFiles !== undefined &&
-          Object.keys(pendingFiles).length > 0
-        ) {
+        const runtime = resolveSessionRuntime({
+          agentRuntime: agent.runtime,
+          cloudOverride: record.cloudOverride,
+        });
+        const hasPendingFiles =
+          pendingFiles !== undefined && Object.keys(pendingFiles).length > 0;
+        if (hasPendingFiles && runtime !== "cloud") {
           const root = await this.resolveFileSystem({
             sessionId,
             continuationKey: record.continuationKey ?? undefined,
@@ -2267,13 +2277,14 @@ export class SessionEngine {
           await writeWorkspaceFilesToRoot(root, pendingFiles);
         }
         if (
-          (pendingFiles !== undefined &&
-            Object.keys(pendingFiles).length > 0) ||
+          (hasPendingFiles && runtime !== "cloud") ||
           (pendingImages !== undefined && pendingImages.length > 0)
         ) {
           await this.updateRecord(sessionId, (current) => ({
             ...current,
             pendingWorkspaceFiles:
+              hasPendingFiles &&
+              runtime !== "cloud" &&
               current.pendingWorkspaceFiles === pendingFiles
                 ? undefined
                 : current.pendingWorkspaceFiles,
@@ -2441,6 +2452,7 @@ export class SessionEngine {
               data: { message: outcome.errorMessage ?? "task failed" },
             }
       );
+      await this.wipeCloudSessionWorkspace(sessionId);
     } else {
       await this.appendEvent(sessionId, {
         type: "session.waiting",
@@ -2495,6 +2507,68 @@ export class SessionEngine {
     );
   }
 
+  /**
+   * Replace this session's store prefix with the pending `workspaceFiles`.
+   * Undefined when the write did not land; the prompt must not name the
+   * mount, matching ensureCloudWorkspaceSynced.
+   */
+  private async syncCloudSessionWorkspaceFiles(
+    store: CloudStoreTarget,
+    sessionId: string,
+    files: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<{ dir: string; relPaths: string[] } | undefined> {
+    const workspacePrefix = store.sessionWorkspacePrefix(sessionId);
+    try {
+      const relPaths = await syncSessionWorkspaceFiles({
+        sink: store.sink,
+        files,
+        workspacePrefix,
+      });
+      return {
+        dir: `${store.mountPath}/${workspacePrefix}`,
+        relPaths,
+      };
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files sync failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      if (error instanceof WorkspaceFileRefusal) {
+        await this.clearPendingWorkspaceFiles(sessionId, files);
+      }
+      return undefined;
+    }
+  }
+
+  private async wipeCloudSessionWorkspace(sessionId: string): Promise<void> {
+    const store = this.cloudStore();
+    if (store === undefined) {
+      return;
+    }
+    try {
+      await wipeSessionWorkspace({
+        sink: store.sink,
+        workspacePrefix: store.sessionWorkspacePrefix(sessionId),
+      });
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files wipe failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  private async clearPendingWorkspaceFiles(
+    sessionId: string,
+    pending: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingWorkspaceFiles:
+        current.pendingWorkspaceFiles === pending
+          ? undefined
+          : current.pendingWorkspaceFiles,
+    }));
+  }
+
   /**
    * With files authored, every first cloud turn re-copies the authored
    * bytes and the memo only dedupes concurrent first turns. The mount is
@@ -2547,6 +2621,8 @@ export class SessionEngine {
       mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
       skillsPrefix: agentStoreKeys.skillsPrefix(),
       workspacePrefix: agentStoreKeys.workspacePrefix(),
+      sessionWorkspacePrefix: (sessionId: string) =>
+        agentStoreKeys.sessionWorkspacePrefix(sessionId),
       label: "deployment store",
     };
     if (v2Hosting.kind === "cursor-managed") {
@@ -2569,6 +2645,11 @@ export class SessionEngine {
         mountPath: USER_STORE_MOUNT_PATH,
         skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
         workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
+        sessionWorkspacePrefix: (sessionId: string) =>
+          agentStoreKeys.userSessionWorkspacePrefix(
+            this.project.name,
+            sessionId
+          ),
         label: "user store",
       };
     }
@@ -2690,34 +2771,39 @@ export class SessionEngine {
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
-    if (isFirstTurn) {
-      if (runtime === "cloud") {
-        // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies. Authored skills and workspace
-        // seeds land on the store mount (skills for native discovery, seeds
-        // for the model's file tools), and on hosted deployments the shared
-        // memory journal is on that mount too — say where. When the turn
-        // carries the session-bound server-tool MCP endpoint, the preamble
-        // catalogs server tools under that MCP server name *before* the
-        // agent-tool "write the script if missing" recipe, so a model told
-        // to "use <server tool>" calls MCP instead of inventing a .sh.
-        const preamble = buildAgentsMdContent(agent, {
+    if (runtime === "cloud") {
+      // Cloud VMs have no materialized workspace: ship the full context,
+      // including agent tool script bodies. Authored skills and workspace
+      // seeds land on the store mount (skills for native discovery, seeds
+      // for the model's file tools), per-turn workspaceFiles land under
+      // the session prefix, and on hosted deployments the shared memory
+      // journal is on that mount too — say where. When the turn carries
+      // the session-bound server-tool MCP endpoint, the preamble catalogs
+      // server tools under that MCP server name *before* the agent-tool
+      // "write the script if missing" recipe, so a model told to "use
+      // <server tool>" calls MCP instead of inventing a .sh.
+      const hosted = isCursorHostedFilesAvailable();
+      const store =
+        hosted || isCursorUserStoreFilesAvailable()
+          ? this.cloudStore()
+          : undefined;
+      let preamble = "";
+      const sections: string[] = [];
+      const pending = record.pendingWorkspaceFiles;
+      if (isFirstTurn) {
+        preamble = buildAgentsMdContent(agent, {
           includeScripts: true,
           serverToolsMcpName:
             this.cloudServerToolsConnection === undefined
               ? undefined
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
-        const hosted = isCursorHostedFilesAvailable();
-        // Synced whenever a store is reachable, not just when skills or
-        // seeds exist: removing the last one has to delete its store copies
-        // too.
-        const store =
-          hosted || isCursorUserStoreFilesAvailable()
-            ? this.cloudStore()
-            : undefined;
-        let sections = "";
-        if (store !== undefined) {
+      }
+      if (store !== undefined) {
+        if (isFirstTurn) {
+          // Synced whenever a store is reachable, not just when skills or
+          // seeds exist: removing the last one has to delete its store copies
+          // too.
           const [, seedsSynced] = await Promise.all([
             this.ensureCloudSkillsSynced(store),
             this.ensureCloudWorkspaceSynced(store),
@@ -2725,37 +2811,63 @@ export class SessionEngine {
           // Only name the mount when the bytes landed; a failed sync must
           // not send the model looking for files that are not there.
           if (seedsSynced && agent.seedFiles.length > 0) {
-            const dir = `${store.mountPath}/${store.workspacePrefix}`;
-            sections += `\n\n${buildCloudWorkspaceSection(dir)}`;
+            sections.push(
+              buildCloudWorkspaceSection(
+                `${store.mountPath}/${store.workspacePrefix}`
+              )
+            );
           }
         }
-        if (hosted) {
-          sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
+        if (pending !== undefined && Object.keys(pending).length > 0) {
+          const synced = await this.syncCloudSessionWorkspaceFiles(
+            store,
+            record.sessionId,
+            pending
+          );
+          if (synced !== undefined) {
+            sections.push(
+              buildCloudSessionWorkspaceSection(synced.dir, synced.relPaths)
+            );
+            await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+          }
         }
-        turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
-      } else if (runtime === "local" && authoredRoot) {
-        // Virtual roots skip materialize, so AGENTS.md never lands on disk.
-        // Ship the same preamble the borrowed-cwd local path uses.
-        const preamble = buildAgentsMdContent(
-          { ...agent, tools: [...agent.tools, ...synthesized] },
-          { includeScripts: true }
-        );
-        const workspaceInfo = `<user_info>\nWorkspace Path: /\n</user_info>`;
-        turnPrompt =
-          preamble === ""
-            ? `${workspaceInfo}\n\n${turnPrompt}`
-            : `${workspaceInfo}\n\n${preamble}\n\n${turnPrompt}`;
-      } else if (runtime === "local" && instructionsInvisibleToHarness) {
-        // Local workspace whose AGENTS.md the harness will not load. With a
-        // borrowed harness cwd, agent tool scripts live only in the durable
-        // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-        // reference on-disk paths under the harness cwd. Grokbot turns are
-        // excluded: their instructions ride the request's `instructions`
-        // field into the Sand system prompt instead.
-        const includeScripts = this.hasBorrowedWorkspace(record);
-        const preamble = buildAgentsMdContent(agent, { includeScripts });
-        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+      } else if (pending !== undefined && Object.keys(pending).length > 0) {
+        await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+      }
+      if (isFirstTurn && hosted) {
+        sections.push(buildCloudMemorySection(this.project.name));
+      }
+      if (preamble !== "" || sections.length > 0) {
+        turnPrompt = [preamble, ...sections, turnPrompt]
+          .filter((part) => part !== "")
+          .join("\n\n");
       }
+    } else if (isFirstTurn && runtime === "local" && authoredRoot) {
+      // Virtual roots skip materialize, so AGENTS.md never lands on disk.
+      // Ship the same preamble the borrowed-cwd local path uses.
+      const preamble = buildAgentsMdContent(
+        { ...agent, tools: [...agent.tools, ...synthesized] },
+        { includeScripts: true }
+      );
+      const workspaceInfo = `<user_info>\nWorkspace Path: /\n</user_info>`;
+      turnPrompt =
+        preamble === ""
+          ? `${workspaceInfo}\n\n${turnPrompt}`
+          : `${workspaceInfo}\n\n${preamble}\n\n${turnPrompt}`;
+    } else if (
+      isFirstTurn &&
+      runtime === "local" &&
+      instructionsInvisibleToHarness
+    ) {
+      // Local workspace whose AGENTS.md the harness will not load. With a
+      // borrowed harness cwd, agent tool scripts live only in the durable
+      // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+      // reference on-disk paths under the harness cwd. Grokbot turns are
+      // excluded: their instructions ride the request's `instructions`
+      // field into the Sand system prompt instead.
+      const includeScripts = this.hasBorrowedWorkspace(record);
+      const preamble = buildAgentsMdContent(agent, { includeScripts });
+      turnPrompt = `${preamble}\n\n${turnPrompt}`;
     }
     return {
       sessionId: record.sessionId,
@@ -4632,6 +4744,10 @@ export class SessionEngine {
    * conversation whose blobs persisted but whose record (which selects the
    * conversation to hydrate) never reached the sink. No-op without a
    * storage mirror.
+   *
+   * Under a debounced event policy the turn-end flush is a timer, not the
+   * chain's tail, so flush explicitly before waiting on the queue; a no-op
+   * when the chain already flushed.
    */
   async drainSessionDurability(sessionId: string): Promise<void> {
     if (this.storage === undefined) {
@@ -4641,6 +4757,7 @@ export class SessionEngine {
     if (chain !== undefined) {
       await chain.catch(() => {});
     }
+    this.storage.flushSession(sessionId);
     await this.storage.whenIdle();
   }
 

package/src/internal/store-mirror.ts

@@ -1,7 +1,7 @@
 /**
  * Mirror an authored file tree onto an Agent Store prefix. Shared by the
- * skills and workspace seed syncs so both keep the same write-then-sweep
- * discipline and the same path refusals.
+ * skills, workspace seed, and session workspaceFile syncs so they keep the
+ * same write-then-sweep discipline and the same path refusals.
  */
 
 import { posix } from "node:path";

package/src/internal/tenant-slack/relay.ts

@@ -109,13 +109,22 @@ export async function postRelaySlackMessage(args: {
   resolve?: () => RelaySlackPostTarget | undefined;
   fetchImpl?: typeof fetch;
   timeoutMs?: number;
+  /** Diagnostic sink; defaults to `console.info`. */
+  log?: (line: string) => void;
 }): Promise<RelaySlackPostResult> {
   const channel = args.channel.trim();
+  const log = args.log ?? ((line: string) => console.info(line));
   if (channel === "") {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid}: empty channel`
+    );
     return { ok: false, channel, status: 0, error: "empty channel" };
   }
   const target = (args.resolve ?? resolveRelaySlackTarget)();
   if (target === undefined) {
+    log(
+      `[agent-sdk-slack-relay-client] refusing post automationUuid=${args.automationUuid} channel=${channel}: no Cursor credential resolved (CURSOR_API_KEY / pod credential absent)`
+    );
     return {
       ok: false,
       channel,
@@ -128,6 +137,11 @@ export async function postRelaySlackMessage(args: {
     baseUrl: target.relayBaseUrl,
     automationUuid: args.automationUuid,
   });
+  const messageChars = args.message.length;
+  log(
+    `[agent-sdk-slack-relay-client] POST ${url} channel=${channel} messageChars=${String(messageChars)} truncated=${String(messageChars > AGENT_SDK_SLACK_RELAY_MAX_MESSAGE_CHARS)} threaded=${String(args.threadTs !== undefined)} timeoutMs=${String(args.timeoutMs ?? DEFAULT_TIMEOUT_MS)}`
+  );
+  const startedAt = Date.now();
   let response: Response;
   try {
     response = await fetchImpl(url, {
@@ -145,6 +159,9 @@ export async function postRelaySlackMessage(args: {
       signal: AbortSignal.timeout(args.timeoutMs ?? DEFAULT_TIMEOUT_MS),
     });
   } catch (error) {
+    log(
+      `[agent-sdk-slack-relay-client] request failed before a response channel=${channel} automationUuid=${args.automationUuid} elapsedMs=${String(Date.now() - startedAt)}: ${describeError(error)}`
+    );
     return { ok: false, channel, status: 0, error: describeError(error) };
   }
   let body: unknown;
@@ -158,16 +175,23 @@ export async function postRelaySlackMessage(args: {
       ? (body as Record<string, unknown>)
       : {};
   if (!response.ok || record.ok !== true) {
+    const error =
+      typeof record.error === "string" && record.error !== ""
+        ? record.error
+        : `relay responded ${response.status}`;
+    log(
+      `[agent-sdk-slack-relay-client] relay denied channel=${channel} automationUuid=${args.automationUuid} status=${String(response.status)} bodyOk=${String(record.ok)} elapsedMs=${String(Date.now() - startedAt)}: ${error}`
+    );
     return {
       ok: false,
       channel,
       status: response.status,
-      error:
-        typeof record.error === "string" && record.error !== ""
-          ? record.error
-          : `relay responded ${response.status}`,
+      error,
     };
   }
+  log(
+    `[agent-sdk-slack-relay-client] relay posted channel=${typeof record.channel === "string" ? record.channel : channel} automationUuid=${args.automationUuid} status=${String(response.status)} ts=${typeof record.ts === "string" ? record.ts : "<none>"} elapsedMs=${String(Date.now() - startedAt)}`
+  );
   return {
     ok: true,
     channel: typeof record.channel === "string" ? record.channel : channel,

package/src/internal/workspace-sync.ts

@@ -1,10 +1,10 @@
 /**
- * Sync `agent/sandbox/workspace/**` seed files onto an Agent Store so
- * cloud-runtime turns read them from the store mount (the first cloud prompt
- * names the directory; see `buildCloudWorkspaceSection`). Hosted deployments
- * write store-root `workspace/<path>`. Local `serve`/`run` with
- * `runtime: "cloud"` writes `agent-serve/<agent>/workspace/<path>` on the
- * USER store.
+ * Sync workspace trees onto an Agent Store so cloud-runtime turns read
+ * them from the store mount. Authored `agent/sandbox/workspace/**` seeds
+ * land at store-root `workspace/<path>` (see `buildCloudWorkspaceSection`).
+ * Per-turn `workspaceFiles` land at `sessions/<sessionId>/workspace/<path>`
+ * (see `buildCloudSessionWorkspaceSection`). Personal-key local+cloud
+ * nests both under `agent-serve/<agent>/`.
  */
 
 import { readFile } from "node:fs/promises";
@@ -13,6 +13,15 @@ import { MEMORY_DIR_NAME } from "../memory.js";
 import type { SeedFile } from "../types.js";
 import { mirrorToStore, storeRelPath } from "./store-mirror.js";
 
+export type WorkspaceFileBody =
+  | string
+  | { encoding: "base64"; data: string; mimeType?: string };
+
+/** Path or encoding that can never land. Distinct from a store outage. */
+export class WorkspaceFileRefusal extends Error {
+  override readonly name = "WorkspaceFileRefusal";
+}
+
 /**
  * Mirror the seed tree onto the store at its authored relative paths and
  * delete keys no seed claims so redeploys drop removed files. Every seed
@@ -30,7 +39,7 @@ export async function syncWorkspaceToStore(args: {
   for (const seed of args.seedFiles) {
     desired.set(
       agentStoreKeys.workspaceFile(
-        seedRelPath(seed.relativePath),
+        workspaceRelPath(seed.relativePath),
         workspacePrefix
       ),
       await readFile(seed.sourcePath)
@@ -39,17 +48,80 @@ export async function syncWorkspaceToStore(args: {
   await mirrorToStore({ sink: args.sink, prefix: workspacePrefix, desired });
 }
 
+/**
+ * Replace the session workspace prefix with this turn's `workspaceFiles`.
+ * Keys the map does not claim are deleted so a later send cannot leave a
+ * stale `pr.json`. Every path validates before the store is touched.
+ * Returns the relative paths that landed, in send order.
+ */
+export async function syncSessionWorkspaceFiles(args: {
+  sink: FileSink;
+  files: Record<string, WorkspaceFileBody>;
+  workspacePrefix: string;
+}): Promise<string[]> {
+  const desired = new Map<string, Uint8Array>();
+  const relPaths: string[] = [];
+  for (const [relativePath, contents] of Object.entries(args.files)) {
+    const rel = workspaceRelPath(relativePath);
+    desired.set(
+      agentStoreKeys.workspaceFile(rel, args.workspacePrefix),
+      workspaceFileBytes(relativePath, contents)
+    );
+    relPaths.push(rel);
+  }
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired,
+  });
+  return relPaths;
+}
+
+/** Delete every key under the session workspace prefix. */
+export async function wipeSessionWorkspace(args: {
+  sink: FileSink;
+  workspacePrefix: string;
+}): Promise<void> {
+  await mirrorToStore({
+    sink: args.sink,
+    prefix: args.workspacePrefix,
+    desired: new Map(),
+  });
+}
+
 /**
  * Same reservation as local materialization's `resolveWorkspaceWritePath`:
- * `memory/` is the shared cross-session journal, so a seed under it fails
- * the sync exactly as it fails a local first turn.
+ * `memory/` is the shared cross-session journal, so a seed or send under it
+ * fails the sync exactly as it fails a local first turn.
  */
-function seedRelPath(relPath: string): string {
-  const rel = storeRelPath(relPath, "workspace file");
+function workspaceRelPath(relPath: string): string {
+  let rel: string;
+  try {
+    rel = storeRelPath(relPath, "workspace file");
+  } catch (error) {
+    throw new WorkspaceFileRefusal(
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (rel.split("/", 1)[0] === MEMORY_DIR_NAME) {
-    throw new Error(
+    throw new WorkspaceFileRefusal(
       `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to sync ${relPath}`
     );
   }
   return rel;
 }
+
+function workspaceFileBytes(
+  relativePath: string,
+  contents: WorkspaceFileBody
+): Uint8Array {
+  if (typeof contents === "string") {
+    return new TextEncoder().encode(contents);
+  }
+  if (contents.encoding === "base64") {
+    return new Uint8Array(Buffer.from(contents.data, "base64"));
+  }
+  throw new WorkspaceFileRefusal(
+    `Unsupported workspace file encoding for ${relativePath}`
+  );
+}

package/src/internal/workspace.ts

@@ -80,6 +80,26 @@ export function buildCloudWorkspaceSection(dir: string): string {
   ].join("\n");
 }
 
+/**
+ * Per-turn preamble for cloud `workspaceFiles` after they land on the
+ * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
+ * the sync did not land.
+ *
+ * Same shared Agent Store mount as authored seeds — the session path is
+ * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
+ */
+export function buildCloudSessionWorkspaceSection(
+  dir: string,
+  relPaths: readonly string[]
+): string {
+  const listed = relPaths.map((path) => `\`${path}\``).join(", ");
+  return [
+    "## Session workspace files",
+    "",
+    `This turn's workspace files live at \`${dir}\` on this machine (${listed}). Read them with your normal file tools. They sit on the same shared Agent Store mount as authored workspace seeds; the session directory is replaced on the next send for this session, and task sessions remove it when they finish.`,
+  ].join("\n");
+}
+
 /** Relative path of an agent-side tool script inside the session workspace. */
 export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;

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);
+}