@cursor/july 0.1.1 → 0.1.2

package/src/internal/discovery.ts

@@ -19,8 +19,10 @@ import {
 import { pathToFileURL } from "node:url";
 import { type ABConfigFile, resolveABMaxPlaygroundSessions } from "../ab.js";
 import { httpChannel } from "../channels.js";
+import type { StorageDefinition } from "../storage.js";
 import {
   type AgentConfigDefinition,
+  type AgentHostingOptions,
   type AgentProject,
   type AgentProjectInfo,
   type ChannelDefinition,
@@ -51,6 +53,12 @@ import { registerAuthoredModuleLoaders } from "./authored-loaders.js";
 import { getDefinitionKind } from "./brand.js";
 import { isValidCron } from "./cron.js";
 import { parseFrontmatter } from "./frontmatter.js";
+import {
+  isReservedSecretName,
+  MAX_EGRESS_DOMAINS,
+  validateEgressDomain,
+  validateSecretName,
+} from "./hosting.js";
 import { toolInputJsonSchema } from "./json-schema.js";
 import { MCP_ENDPOINT_PATH, mcpEndpointToolNames } from "./mcp-endpoint.js";
 
@@ -233,6 +241,7 @@ export async function loadAgentProject(
   const hooks = await loadHooks(ctx, join(agentDir, "hooks"));
   const abs = await loadABs(ctx, agentDir);
   const abConfig = await loadABConfig(ctx, agentDir);
+  const storage = await loadStorage(ctx, agentDir);
 
   if (agentDir !== rootDir) {
     await warnUnknownSlots(ctx, agentDir);
@@ -248,7 +257,8 @@ export async function loadAgentProject(
     schedules,
     hooks,
     abs,
-    ...(abConfig === undefined ? {} : { abConfig }),
+    abConfig,
+    storage,
     diagnostics,
   };
 }
@@ -324,6 +334,7 @@ async function loadAgent(
       : {
           cwd: localCwd,
         };
+  const hosting = resolveHosting(ctx, agentDir, config?.hosting);
 
   if (runtime === "cloud") {
     warnCloudRuntimeLimitations(ctx, agentDir, {
@@ -344,6 +355,7 @@ async function loadAgent(
     runtime,
     cloud,
     local,
+    hosting,
     tools,
     skills,
     connections,
@@ -367,6 +379,59 @@ function resolveAgentCwd(
   return isAbsolute(trimmed) ? trimmed : resolve(ctx.rootDir, trimmed);
 }
 
+/**
+ * Validate the authored `hosting` block against the same grammar the
+ * backend enforces on deploy. Violations are warning diagnostics (reported
+ * by `agentkit validate`), not hard failures: the backend stays
+ * authoritative and `agentkit deploy` re-checks before any network call.
+ */
+function resolveHosting(
+  ctx: DiscoveryContext,
+  agentDir: string,
+  hosting: AgentHostingOptions | undefined
+): AgentHostingOptions | undefined {
+  if (hosting === undefined) {
+    return undefined;
+  }
+  const agentPath = displayPath(ctx, join(agentDir, "agent.ts"));
+  const warn = (message: string): void => {
+    ctx.diagnostics.push({ severity: "warning", path: agentPath, message });
+  };
+
+  const egressDomains = hosting.egressDomains ?? [];
+  for (const domain of egressDomains) {
+    const domainError = validateEgressDomain(domain);
+    if (domainError !== undefined) {
+      warn(`hosting.egressDomains: ${domainError}`);
+    }
+  }
+  if (egressDomains.length > MAX_EGRESS_DOMAINS) {
+    warn(
+      `hosting.egressDomains lists ${egressDomains.length} domains; deploys are capped at ${MAX_EGRESS_DOMAINS}.`
+    );
+  }
+
+  for (const name of hosting.secretNames ?? []) {
+    const nameError = validateSecretName(name);
+    if (nameError !== undefined) {
+      warn(`hosting.secretNames: ${nameError}`);
+    } else if (isReservedSecretName(name)) {
+      warn(
+        `hosting.secretNames: ${JSON.stringify(name)} is platform-reserved (CURSOR_*) and injected automatically; it cannot be set with \`secrets set\`.`
+      );
+    }
+  }
+
+  return {
+    ...(hosting.egressDomains === undefined
+      ? {}
+      : { egressDomains: [...hosting.egressDomains] }),
+    ...(hosting.secretNames === undefined
+      ? {}
+      : { secretNames: [...hosting.secretNames] }),
+  };
+}
+
 async function loadAgentConfig(
   ctx: DiscoveryContext,
   agentDir: string,
@@ -1323,6 +1388,22 @@ async function loadABConfig(
   }
 }
 
+// ============================================================================
+// Storage (agent/storage.ts)
+// ============================================================================
+
+async function loadStorage(
+  ctx: DiscoveryContext,
+  agentDir: string
+): Promise<StorageDefinition | undefined> {
+  const path = await findModuleFile(agentDir, "storage");
+  if (path === undefined) {
+    return undefined;
+  }
+  const definition = await importDefault(ctx, path, "storage");
+  return definition as StorageDefinition | undefined;
+}
+
 function resolveABName(definition: unknown, fallback: string): string {
   if (
     typeof definition === "object" &&
@@ -1410,6 +1491,7 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
     cloud:
       agent.cloud === undefined ? undefined : toPublicCloudInfo(agent.cloud),
     local: agent.local,
+    hosting: agent.hosting,
     mcp: { path: MCP_ENDPOINT_PATH, tools: mcpEndpointToolNames(project) },
     instructions:
       agent.instructions === undefined
@@ -1496,6 +1578,10 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
             durableSnapshots: project.abConfig?.persistSnapshots !== undefined,
           },
         }),
+    storage:
+      project.storage === undefined
+        ? undefined
+        : { name: project.storage.name },
     diagnostics: project.diagnostics,
   };
 }
@@ -1515,6 +1601,7 @@ async function importDefault(
     | "schedule"
     | "hook"
     | "ab"
+    | "storage"
 ): Promise<unknown> {
   let mod: Record<string, unknown>;
   try {

package/src/internal/distribution.ts

@@ -94,4 +94,5 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["hooks", "hooks.js"],
   ["evals", "evals.js"],
   ["ab", "ab.js"],
+  ["storage", "storage.js"],
 ];

package/src/internal/eval-run-store.ts

@@ -62,9 +62,21 @@ export class EvalRunStore {
 
   constructor(
     private readonly projectRoot: string,
-    private readonly logger: (line: string) => void
+    private readonly logger: (line: string) => void,
+    /**
+     * Project-wide sink from `agent/storage.ts` (`defineStorage`),
+     * used when `evals.config.ts` sets no `persistRuns` of its own.
+     */
+    private readonly fallbackPersistence?: EvalRunPersistence
   ) {}
 
+  /** `evals.config.ts` `persistRuns` wins; `defineStorage` is fallback. */
+  private resolvePersist(
+    config: Partial<EvalConfigFile>
+  ): EvalRunPersistence | undefined {
+    return config.persistRuns ?? this.fallbackPersistence;
+  }
+
   async list(): Promise<{
     evals: Array<{
       id: string;
@@ -74,7 +86,7 @@ export class EvalRunStore {
     }>;
     config: EvalListConfig;
   }> {
-    await this.ensureHydrated();
+    await this.hydrate();
     const { evals, config } = await discoverEvals(this.projectRoot);
     return {
       evals: evals.map((e) => ({
@@ -85,18 +97,21 @@ export class EvalRunStore {
           : { description: e.definition.description }),
         ...(e.definition.tags === undefined ? {} : { tags: e.definition.tags }),
       })),
-      config: snapshotListConfig(config),
+      config: snapshotListConfig(
+        config,
+        this.resolvePersist(config) !== undefined
+      ),
     };
   }
 
   async get(runId: string): Promise<EvalRunSnapshot | undefined> {
-    await this.ensureHydrated();
+    await this.hydrate();
     return this.runs.get(runId);
   }
 
   /** Newest-first snapshots for playground rehydrate after navigation/reload. */
   async listRuns(): Promise<EvalRunSnapshot[]> {
-    await this.ensureHydrated();
+    await this.hydrate();
     return this.sortedRuns();
   }
 
@@ -109,7 +124,7 @@ export class EvalRunStore {
     runs: EvalRunSnapshot[];
     activeRunId?: string;
   }> {
-    await this.ensureHydrated();
+    await this.hydrate();
     const activeRunId = this.activeRunId;
     return {
       runs: this.sortedRuns(),
@@ -122,7 +137,7 @@ export class EvalRunStore {
   }
 
   async start(input: StartEvalRunInput = {}): Promise<EvalRunSnapshot> {
-    await this.ensureHydrated();
+    await this.hydrate();
     if (this.activeRunId !== undefined) {
       const active = this.runs.get(this.activeRunId);
       if (active !== undefined && active.status === "running") {
@@ -160,12 +175,15 @@ export class EvalRunStore {
         done: 0,
       },
       cases,
-      config: snapshotRunConfig(config),
+      config: snapshotRunConfig(
+        config,
+        this.resolvePersist(config) !== undefined
+      ),
     };
     this.runs.set(runId, snapshot);
     this.activeRunId = runId;
     await this.pruneOldRuns(config);
-    await this.enqueuePersist(snapshot, config.persistRuns);
+    await this.enqueuePersist(snapshot, this.resolvePersist(config));
     this.logger(
       `[agent-serve] eval run ${runId}: starting ${cases.length} case(s)`
     );
@@ -189,7 +207,14 @@ export class EvalRunStore {
     );
   }
 
-  private async ensureHydrated(): Promise<void> {
+  /**
+   * Hydrate playground eval history from durable persistence
+   * (`evals.config.ts` `persistRuns`, else the `defineStorage`
+   * fallback). Called eagerly from the serve startup restore step —
+   * alongside session restore — and lazily as a safety net by every read.
+   * Idempotent; concurrent callers share one pass.
+   */
+  async hydrate(): Promise<void> {
     if (this.hydrated) {
       return;
     }
@@ -202,7 +227,7 @@ export class EvalRunStore {
   private async hydrateFromPersistence(): Promise<void> {
     try {
       const { config } = await discoverEvals(this.projectRoot);
-      const persist = config.persistRuns;
+      const persist = this.resolvePersist(config);
       if (persist === undefined) {
         this.hydrated = true;
         return;
@@ -260,7 +285,7 @@ export class EvalRunStore {
         continue;
       }
       this.runs.delete(stale.runId);
-      await this.persistDelete(stale.runId, config.persistRuns);
+      await this.persistDelete(stale.runId, this.resolvePersist(config));
     }
   }
 
@@ -384,7 +409,7 @@ export class EvalRunStore {
           this.applyCaseResult(runId, result);
           const run = this.runs.get(runId);
           if (run !== undefined) {
-            void this.enqueuePersist(run, opts.config.persistRuns);
+            void this.enqueuePersist(run, this.resolvePersist(opts.config));
           }
         },
       });
@@ -394,7 +419,7 @@ export class EvalRunStore {
       }
       run.status = "completed";
       run.finishedAt = new Date().toISOString();
-      await this.enqueuePersist(run, opts.config.persistRuns);
+      await this.enqueuePersist(run, this.resolvePersist(opts.config));
       this.logger(
         `[agent-serve] eval run ${runId}: done — ${run.summary.passed} passed, ${run.summary.failed} failed`
       );
@@ -406,7 +431,7 @@ export class EvalRunStore {
       run.status = "failed";
       run.finishedAt = new Date().toISOString();
       run.error = error instanceof Error ? error.message : String(error);
-      await this.enqueuePersist(run, opts.config.persistRuns);
+      await this.enqueuePersist(run, this.resolvePersist(opts.config));
       this.logger(`[agent-serve] eval run ${runId}: failed — ${run.error}`);
     } finally {
       if (this.activeRunId === runId) {
@@ -467,21 +492,25 @@ function markInterruptedRun(run: EvalRunSnapshot): void {
   }
 }
 
-function snapshotListConfig(config: Partial<EvalConfigFile>): EvalListConfig {
+function snapshotListConfig(
+  config: Partial<EvalConfigFile>,
+  durableRuns: boolean
+): EvalListConfig {
   return {
     ...(config.maxConcurrency === undefined
       ? {}
       : { maxConcurrency: config.maxConcurrency }),
     ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
     maxPlaygroundRuns: resolveEvalMaxPlaygroundRuns(config.maxPlaygroundRuns),
-    durableRuns: config.persistRuns !== undefined,
+    durableRuns,
   };
 }
 
 function snapshotRunConfig(
-  config: Partial<EvalConfigFile>
+  config: Partial<EvalConfigFile>,
+  durableRuns: boolean
 ): EvalRunSnapshot["config"] {
-  const list = snapshotListConfig(config);
+  const list = snapshotListConfig(config, durableRuns);
   return {
     ...(list.maxConcurrency === undefined
       ? {}

package/src/internal/handleAgentServeTrigger.ts

@@ -62,19 +62,17 @@ export function collectGitHubTriggerTargets(input: {
 }): AgentServeGitHubTriggerTarget[] {
   const targets: AgentServeGitHubTriggerTarget[] = [];
   for (const mount of input.mounts) {
-    const github = mount.channels.find((channel) => channel.id === "github");
-    if (github === undefined) {
-      continue;
+    for (const channel of mount.channels) {
+      const options = getGitHubChannelOptions(channel.definition);
+      if (options === undefined) {
+        continue;
+      }
+      targets.push({
+        slug: mount.slug,
+        options,
+        args: mount.buildHandlerArgs(channel.id),
+      });
     }
-    const options = getGitHubChannelOptions(github.definition);
-    if (options === undefined) {
-      continue;
-    }
-    targets.push({
-      slug: mount.slug,
-      options,
-      args: mount.buildHandlerArgs("github"),
-    });
   }
   return targets;
 }

package/src/internal/host-platforms.ts

@@ -12,6 +12,7 @@ import {
   resolveGitHubInstallationId,
   tryResolveGhAuthToken,
 } from "../channels/github/auth.js";
+import type { GitHubChannelCredentials } from "../channels/github/types.js";
 import { tryResolveBotToken } from "../channels/slack/credentials.js";
 import type { HostGitHubClient, HostSlackClient } from "../types.js";
 
@@ -25,21 +26,34 @@ export interface HostPlatforms {
  * `app` = GitHub App installation token (preferred in production).
  * `env` / `gh` = local PAT / CLI fallbacks when App creds are unset.
  */
-export type HostGitHubAuthSource = "app" | "env" | "gh" | "unavailable";
+export type HostGitHubAuthSource =
+  | "app"
+  | "cursor-account"
+  | "env"
+  | "gh"
+  | "unavailable";
+
+export interface HostPlatformsOptions {
+  githubCredentials?: GitHubChannelCredentials;
+}
 
 /**
  * Build host platforms from ambient credentials. Prefer App installation
  * auth when configured; otherwise fall back to PAT / `gh auth` for local
  * testing. Webhook-scoped calls should still prefer `ctx.github`.
  */
-export function createHostPlatforms(): HostPlatforms {
+export function createHostPlatforms(
+  options: HostPlatformsOptions = {}
+): HostPlatforms {
   let octokitPromise: ReturnType<HostGitHubClient["getOctokit"]> | undefined;
   let slackPromise: ReturnType<HostSlackClient["getClient"]> | undefined;
 
   return {
     github: {
       getOctokit: () => {
-        octokitPromise ??= createGitHubOctokit({});
+        octokitPromise ??= createGitHubOctokit({
+          credentials: options.githubCredentials,
+        });
         return octokitPromise;
       },
     },
@@ -95,8 +109,9 @@ export async function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSourc
 export async function warmupHostGitHubAuth(options: {
   logger: (line: string) => void;
   github?: HostGitHubClient;
+  authSource?: HostGitHubAuthSource;
 }): Promise<HostGitHubAuthSource> {
-  const source = await resolveHostGitHubAuthSource();
+  const source = options.authSource ?? (await resolveHostGitHubAuthSource());
   if (source === "unavailable") {
     options.logger(
       "[agent-serve] GitHub auth: unavailable (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)"
@@ -118,13 +133,15 @@ export async function warmupHostGitHubAuth(options: {
   }
 
   const label =
-    source === "app"
-      ? exportedGhToken
-        ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
-        : "GitHub App installation token"
-      : source === "env"
-        ? "GITHUB_TOKEN/GH_TOKEN"
-        : "gh auth token";
+    source === "cursor-account"
+      ? "Cursor account repo-scoped credential (also exported as GH_TOKEN for gh CLI)"
+      : source === "app"
+        ? exportedGhToken
+          ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
+          : "GitHub App installation token"
+        : source === "env"
+          ? "GITHUB_TOKEN/GH_TOKEN"
+          : "gh auth token";
   if (options.github === undefined) {
     options.logger(`[agent-serve] GitHub auth: ${label}`);
     return source;

package/src/internal/hosting.ts

@@ -0,0 +1,77 @@
+/**
+ * Client-side mirrors of the Agent Serve hosting validation rules
+ * (backend/server/src/agentServe/agentServeShared.ts). Shared by discovery
+ * (`hosting` block diagnostics on `agentkit validate`) and the deploy /
+ * secrets CLI verbs (actionable errors before any network call). The
+ * backend stays authoritative — these exist so mistakes fail fast and
+ * locally with the same grammar the server enforces.
+ */
+
+/** `hosting.egressDomains` cap (backend caps the deploy body at 20). */
+export const MAX_EGRESS_DOMAINS = 20;
+/** Max secrets per deployment. */
+export const MAX_SECRETS = 32;
+/** Max secret value size in bytes. */
+export const MAX_SECRET_VALUE_BYTES = 4096;
+/** Max secret name length. */
+export const MAX_SECRET_NAME_LENGTH = 64;
+/** Secret names the platform injects; user writes are rejected. */
+export const RESERVED_SECRET_NAME_PREFIX = "CURSOR_";
+
+const SECRET_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+
+// Lowercase hostname with >=2 labels, an alphabetic TLD, and at most one
+// leading `*.` wildcard. Labels: alphanumeric with interior hyphens.
+const EGRESS_DOMAIN_PATTERN =
+  /^(\*\.)?([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]+$/;
+
+/** Returns a human error message, or undefined when the domain is valid. */
+export function validateEgressDomain(domain: string): string | undefined {
+  if (EGRESS_DOMAIN_PATTERN.test(domain)) {
+    return undefined;
+  }
+  return `Invalid egress domain ${JSON.stringify(domain)}: use a lowercase hostname with at least two labels and an alphabetic TLD (e.g. "api.example.com"), optionally with a single leading "*." wildcard.`;
+}
+
+/**
+ * Returns a human error message, or undefined when the name is a valid
+ * secret name. Grammar only — reserved names are checked separately so the
+ * manifest's declarative `secretNames` can mention them with a softer
+ * diagnostic than the hard write-time rejection.
+ */
+export function validateSecretName(name: string): string | undefined {
+  if (name.length > MAX_SECRET_NAME_LENGTH) {
+    return `Secret name ${JSON.stringify(name)} is too long (max ${MAX_SECRET_NAME_LENGTH} characters).`;
+  }
+  if (!SECRET_NAME_PATTERN.test(name)) {
+    return `Invalid secret name ${JSON.stringify(name)}: use UPPER_SNAKE_CASE starting with a letter (${SECRET_NAME_PATTERN}).`;
+  }
+  return undefined;
+}
+
+/** True when the platform reserves this name (`CURSOR_*`); writes are rejected. */
+export function isReservedSecretName(name: string): boolean {
+  return name.startsWith(RESERVED_SECRET_NAME_PREFIX);
+}
+
+/**
+ * Human error for a secret name a user is trying to write or delete:
+ * grammar plus the reserved `CURSOR_*` prefix.
+ */
+export function validateSettableSecretName(name: string): string | undefined {
+  const nameError = validateSecretName(name);
+  if (nameError !== undefined) {
+    return nameError;
+  }
+  if (isReservedSecretName(name)) {
+    return `Secret name ${JSON.stringify(name)} is platform-reserved (CURSOR_*); the platform injects those values automatically.`;
+  }
+  return undefined;
+}
+
+const CURSOR_EVENT_REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+/** `owner/name` — mirrors the backend's cursor-event repo grammar. */
+export function isValidCursorEventRepo(repo: string): boolean {
+  return CURSOR_EVENT_REPO_PATTERN.test(repo) && !repo.includes("..");
+}

package/src/internal/reminder-runner.ts

@@ -121,6 +121,9 @@ export class ReminderRunner {
   async start(): Promise<void> {
     if (this.started) return;
     this.started = true;
+    // Materialize sink-backed reminders onto local disk before arming
+    // (local wins when both sides have the same id).
+    await this.hydrateFromStorage();
     const armed = await this.store.listArmed();
     let restored = 0;
     let disarmedOrphan = 0;
@@ -148,6 +151,47 @@ export class ReminderRunner {
     }
   }
 
+  /**
+   * Pull reminder records from `defineStorage` into `<stateRoot>/reminders`
+   * when local disk is empty for that id. Failures are logged and skipped.
+   */
+  private async hydrateFromStorage(): Promise<void> {
+    const storage = this.engine.storage;
+    if (storage === undefined || !storage.canBulkRestore) {
+      return;
+    }
+    let hydrated = 0;
+    try {
+      const remote = await storage.listReminders();
+      for (const record of remote) {
+        const local = await this.store.get(record.id);
+        if (local !== undefined) {
+          continue;
+        }
+        // Local write only — re-mirroring would just echo the sink.
+        await this.store.save(record);
+        hydrated += 1;
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger(
+        `[agent-serve] reminders: storage hydrate failed: ${message}`
+      );
+      return;
+    }
+    if (hydrated > 0) {
+      this.logger(
+        `[agent-serve] reminders: hydrated ${hydrated} reminder(s) from storage`
+      );
+    }
+  }
+
+  /** Persist locally and mirror into the authored storage sink when present. */
+  private async persist(record: ReminderRecord): Promise<void> {
+    await this.store.save(record);
+    this.engine.storage?.reminder(record);
+  }
+
   stop(): void {
     this.started = false;
     for (const timer of this.timers.values()) {
@@ -209,7 +253,7 @@ export class ReminderRunner {
       updatedAt: now,
     };
 
-    await this.store.save(record);
+    await this.persist(record);
     this.handlers.set(id, {
       run: input.run,
       untilFn,
@@ -273,7 +317,7 @@ export class ReminderRunner {
       disarmReason: reason,
       updatedAt: new Date().toISOString(),
     };
-    await this.store.save(updated);
+    await this.persist(updated);
     this.handlers.delete(id);
     return toInfo(updated);
   }
@@ -662,7 +706,7 @@ export class ReminderRunner {
       disarmReason: reason,
       updatedAt: new Date().toISOString(),
     };
-    await this.store.save(updated);
+    await this.persist(updated);
     this.handlers.delete(record.id);
   }
 
@@ -711,7 +755,7 @@ export class ReminderRunner {
             : String(reschedule.at),
         updatedAt: new Date().toISOString(),
       };
-      await this.store.save(updated);
+      await this.persist(updated);
       this.armTimer(updated);
       return;
     }
@@ -725,7 +769,7 @@ export class ReminderRunner {
         disarmReason: "one_shot_complete",
         updatedAt: new Date().toISOString(),
       };
-      await this.store.save(updated);
+      await this.persist(updated);
       this.handlers.delete(current.id);
       return;
     }
@@ -747,7 +791,7 @@ export class ReminderRunner {
       nextFireAtMs,
       updatedAt: new Date().toISOString(),
     };
-    await this.store.save(updated);
+    await this.persist(updated);
     this.armTimer(updated);
   }
 }

package/src/internal/reminder-store.ts

@@ -66,6 +66,27 @@ export interface ReminderRecord {
   updatedAt: string;
 }
 
+/** Narrow a sink value to a {@link ReminderRecord} (startup hydrate). */
+export function isReminderRecord(value: unknown): value is ReminderRecord {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Partial<ReminderRecord>;
+  return (
+    record.version === REMINDER_SNAPSHOT_VERSION &&
+    typeof record.id === "string" &&
+    record.id !== "" &&
+    typeof record.purpose === "string" &&
+    typeof record.channelId === "string" &&
+    typeof record.continuationToken === "string" &&
+    typeof record.scheduleKind === "string" &&
+    typeof record.scheduleValue === "string" &&
+    typeof record.status === "string" &&
+    typeof record.nextFireAtMs === "number" &&
+    Number.isFinite(record.nextFireAtMs)
+  );
+}
+
 export class ReminderStore {
   constructor(private readonly rootDir: string) {}