@cursor/july 0.1.105 → 0.1.108

package/dist/internal/reminder-control-plane-protocol.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Versioned internal reminder control-plane protocol.
+ *
+ * CP owns reminder id, status, fireCount, nextFireAt, claim, and
+ * completion/rearm. The guest validates create input and executes an
+ * immutable fire descriptor, returning a structured outcome. Cursor-hosted
+ * HTTP CP is not implemented here; {@link ReminderControlPlane} is the
+ * surface the next backend PR will speak.
+ *
+ * Not part of the public package API — keep behind the internal boundary.
+ */
+import type { JsonObject, ReminderBusyPolicy, ReminderScheduleKind } from "../types.js";
+import type { ReminderRecord } from "./reminder-store.js";
+/** Wire / persistence version for this control-plane protocol. */
+export declare const REMINDER_CP_PROTOCOL_VERSION: 1;
+/** Each recurring/retry fire can spend a model turn and create hosted work. */
+export declare const REMINDER_CP_MIN_RECURRING_INTERVAL_MS: 60000;
+export type ReminderCpProtocolVersion = typeof REMINDER_CP_PROTOCOL_VERSION;
+/**
+ * Normalized raw schedule for create intents (JSON-safe).
+ * CP resolves this into nextFireAtMs / intervalMs — guests must not send
+ * authoritative fire times.
+ */
+export type ReminderScheduleSpec = {
+    kind: "every";
+    every: string;
+} | {
+    kind: "cron";
+    cron: string;
+} | {
+    kind: "delay";
+    delay: string | number;
+} | {
+    kind: "at";
+    at: string;
+};
+/**
+ * Guest → CP create intent. No id/status/fireCount/nextFireAt — CP assigns
+ * those after resolving {@link ReminderScheduleSpec}.
+ */
+export interface ReminderCreateIntent {
+    protocolVersion: ReminderCpProtocolVersion;
+    purpose: string;
+    channelId: string;
+    continuationToken: string;
+    target?: Record<string, unknown>;
+    schedule: ReminderScheduleSpec;
+    prompt?: string;
+    handler?: string;
+    args?: JsonObject;
+    hasRunHandler: boolean;
+    hasUntilFn: boolean;
+    untilPrompt?: string;
+    busyPolicy: ReminderBusyPolicy;
+}
+/**
+ * Immutable fire descriptor issued after CP claim. Guest execution must not
+ * mutate authoritative status/fireCount; it returns {@link ReminderExecutionOutcome}.
+ */
+export interface ReminderFireDescriptor {
+    protocolVersion: ReminderCpProtocolVersion;
+    id: string;
+    /** Fire index being executed (equals record.fireCount at claim time). */
+    fireCount: number;
+    /** CAS generation captured at claim; cancel/rekey bumps it. */
+    generation: number;
+    purpose: string;
+    channelId: string;
+    continuationToken: string;
+    target?: Record<string, unknown>;
+    scheduleKind: ReminderScheduleKind;
+    scheduleValue: string;
+    intervalMs?: number;
+    prompt?: string;
+    handler?: string;
+    args?: JsonObject;
+    hasRunHandler: boolean;
+    hasUntilFn: boolean;
+    untilPrompt?: string;
+    busyPolicy: ReminderBusyPolicy;
+    /** Due time that triggered this claim. */
+    nextFireAtMs: number;
+    claimedAtMs: number;
+}
+/** Claim token used to apply an outcome exactly once for (id, fireCount, generation). */
+export interface ReminderFireClaim {
+    id: string;
+    fireCount: number;
+    generation: number;
+}
+/**
+ * Wire-JSON-safe guest execution outcome. Retry is explicit and keyed by
+ * (id, fireCount) — `"retry"` does not increment fireCount.
+ * `reschedule.at` is an ISO-8601 string (never a Date).
+ */
+export type ReminderExecutionOutcome = {
+    kind: "delivered";
+    /** Optional one-shot reschedule override (same as handler reschedule). */
+    reschedule?: ReminderWireReschedule;
+} | {
+    kind: "skipped";
+    reschedule?: ReminderWireReschedule;
+} | {
+    kind: "stop";
+    reason: string;
+} | {
+    /** Re-arm the same fireCount after an explicit, idempotent retry. */
+    kind: "retry";
+    delayMs?: number;
+    reason?: string;
+};
+/** JSON-safe reschedule override for outcomes / hosted wire. */
+export interface ReminderWireReschedule {
+    delay?: string | number;
+    /** ISO-8601 timestamp — never a Date instance. */
+    at?: string;
+}
+export type ReminderOutcomeApplyResult = {
+    applied: true;
+    record: ReminderRecord;
+} | {
+    applied: false;
+    reason: "missing" | "stale_generation" | "stale_fire_count" | "not_claimed" | "duplicate";
+    record?: ReminderRecord;
+};
+/** Guest executor callback invoked by the CP after a successful claim. */
+export type ReminderGuestExecutor = (descriptor: ReminderFireDescriptor) => Promise<ReminderExecutionOutcome>;
+/**
+ * Control-plane reminder API (local disk today; Cursor-hosted HTTP later).
+ * Extends document CRUD with create-intent, cancel/rekey CAS, and outcome apply.
+ */
+export interface ReminderControlPlane {
+    readonly protocolVersion: ReminderCpProtocolVersion;
+    createReminder(intent: ReminderCreateIntent): Promise<ReminderRecord>;
+    getReminder(id: string): Promise<ReminderRecord | undefined>;
+    listReminders(): Promise<ReminderRecord[]>;
+    cancelReminder(id: string, reason?: string): Promise<ReminderRecord | undefined>;
+    /**
+     * Re-key armed (and in-flight) reminders for a continuation rotation.
+     * Bumps generation so an in-flight outcome cannot land on the old token.
+     */
+    rekeyReminders(channelId: string, oldToken: string, newToken: string): Promise<number>;
+    applyReminderOutcome(claim: ReminderFireClaim, outcome: ReminderExecutionOutcome): Promise<ReminderOutcomeApplyResult>;
+}
+export declare function newReminderId(): string;
+export declare function recordGeneration(record: ReminderRecord): number;
+/** Map a JSON-safe schedule spec into resolveSchedule create fields. */
+export declare function scheduleSpecToCreateFields(schedule: ReminderScheduleSpec): {
+    every?: string;
+    cron?: string;
+    delay?: string | number;
+    at?: string;
+};
+/**
+ * Build a wire-safe schedule spec from guest create input.
+ * Normalizes `at` Dates/numbers to ISO strings.
+ */
+export declare function scheduleSpecFromCreateInput(input: {
+    every?: string;
+    cron?: string;
+    delay?: string | number;
+    at?: Date | string | number;
+}): ReminderScheduleSpec;
+/**
+ * Normalize a guest-facing `at` value to an ISO string for the wire intent.
+ */
+export declare function normalizeScheduleAt(at: Date | string | number): string;
+/** Normalize handler reschedule into a wire-JSON-safe shape. */
+export declare function toWireReschedule(reschedule: {
+    delay?: string | number;
+    at?: Date | string;
+}): ReminderWireReschedule;
+/**
+ * Build a durable record from a create intent. CP owns schedule resolution
+ * via {@link resolveSchedule}; pass `nowMs` for deterministic tests.
+ */
+export declare function intentToNewRecord(intent: ReminderCreateIntent, nowMs?: number): ReminderRecord;
+export declare function toFireDescriptor(record: ReminderRecord, claimedAtMs: number): ReminderFireDescriptor;
+export declare function claimFromDescriptor(descriptor: ReminderFireDescriptor): ReminderFireClaim;
+/** Next fire time from the record's recurring schedule (CP-owned). */
+export declare function nextScheduleFireAtMs(record: ReminderRecord, afterMs: number): number;
+export declare function isOneShotSchedule(kind: ReminderScheduleKind): boolean;
+/**
+ * Pure CAS apply of a guest outcome onto a reminder record.
+ * Callers persist the returned record when `applied: true`.
+ * Requires `status === "firing"` — an armed record was never claimed.
+ */
+export declare function applyOutcomeToRecord(record: ReminderRecord, claim: ReminderFireClaim, outcome: ReminderExecutionOutcome, nowMs?: number): ReminderOutcomeApplyResult;
+//# sourceMappingURL=reminder-control-plane-protocol.d.ts.map

package/dist/internal/reminder-control-plane-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-control-plane-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/reminder-control-plane-protocol.ts"],"names":[],"mappings":"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"}

package/dist/internal/reminder-control-plane-protocol.js

@@ -0,0 +1,251 @@
+/**
+ * Versioned internal reminder control-plane protocol.
+ *
+ * CP owns reminder id, status, fireCount, nextFireAt, claim, and
+ * completion/rearm. The guest validates create input and executes an
+ * immutable fire descriptor, returning a structured outcome. Cursor-hosted
+ * HTTP CP is not implemented here; {@link ReminderControlPlane} is the
+ * surface the next backend PR will speak.
+ *
+ * Not part of the public package API — keep behind the internal boundary.
+ */
+import { randomBytes } from "node:crypto";
+import { parseDuration } from "./duration.js";
+import { nextCronFireMs, ReminderValidationError, resolveSchedule, } from "./reminder-schedule.js";
+/** Wire / persistence version for this control-plane protocol. */
+export const REMINDER_CP_PROTOCOL_VERSION = 1;
+/** Each recurring/retry fire can spend a model turn and create hosted work. */
+export const REMINDER_CP_MIN_RECURRING_INTERVAL_MS = 60000;
+export function newReminderId() {
+    return `rem_${randomBytes(8).toString("hex")}`;
+}
+export function recordGeneration(record) {
+    var _a;
+    return (_a = record.generation) !== null && _a !== void 0 ? _a : 0;
+}
+/** Map a JSON-safe schedule spec into resolveSchedule create fields. */
+export function scheduleSpecToCreateFields(schedule) {
+    switch (schedule.kind) {
+        case "every":
+            return { every: schedule.every };
+        case "cron":
+            return { cron: schedule.cron };
+        case "delay":
+            return { delay: schedule.delay };
+        case "at":
+            return { at: schedule.at };
+    }
+}
+/**
+ * Build a wire-safe schedule spec from guest create input.
+ * Normalizes `at` Dates/numbers to ISO strings.
+ */
+export function scheduleSpecFromCreateInput(input) {
+    const shapes = [
+        input.every !== undefined,
+        input.cron !== undefined,
+        input.delay !== undefined,
+        input.at !== undefined,
+    ].filter(Boolean);
+    if (shapes.length !== 1) {
+        throw new ReminderValidationError("reminders.create requires exactly one of every, cron, delay, or at");
+    }
+    if (input.every !== undefined) {
+        return { kind: "every", every: input.every };
+    }
+    if (input.cron !== undefined) {
+        return { kind: "cron", cron: input.cron };
+    }
+    if (input.delay !== undefined) {
+        return { kind: "delay", delay: input.delay };
+    }
+    return { kind: "at", at: normalizeScheduleAt(input.at) };
+}
+/**
+ * Normalize a guest-facing `at` value to an ISO string for the wire intent.
+ */
+export function normalizeScheduleAt(at) {
+    if (at instanceof Date) {
+        if (!Number.isFinite(at.getTime())) {
+            throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
+        }
+        return at.toISOString();
+    }
+    if (typeof at === "number") {
+        if (!Number.isFinite(at)) {
+            throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
+        }
+        return new Date(at).toISOString();
+    }
+    const ms = Date.parse(at);
+    if (!Number.isFinite(ms)) {
+        throw new ReminderValidationError(`Invalid at time: ${String(at)}`);
+    }
+    // Preserve caller string when it already parses; still wire-safe.
+    return at;
+}
+/** Normalize handler reschedule into a wire-JSON-safe shape. */
+export function toWireReschedule(reschedule) {
+    const out = {};
+    if (reschedule.delay !== undefined) {
+        out.delay = reschedule.delay;
+    }
+    if (reschedule.at !== undefined) {
+        out.at =
+            reschedule.at instanceof Date
+                ? reschedule.at.toISOString()
+                : String(reschedule.at);
+    }
+    return out;
+}
+/**
+ * Build a durable record from a create intent. CP owns schedule resolution
+ * via {@link resolveSchedule}; pass `nowMs` for deterministic tests.
+ */
+export function intentToNewRecord(intent, nowMs = Date.now()) {
+    var _a;
+    if (intent.protocolVersion !== REMINDER_CP_PROTOCOL_VERSION) {
+        throw new ReminderValidationError(`Unsupported reminder CP protocol version ${String(intent.protocolVersion)}`);
+    }
+    const resolved = resolveSchedule(scheduleSpecToCreateFields(intent.schedule), nowMs);
+    if (resolved.kind === "every" &&
+        ((_a = resolved.intervalMs) !== null && _a !== void 0 ? _a : 0) < REMINDER_CP_MIN_RECURRING_INTERVAL_MS) {
+        throw new ReminderValidationError(`every must be >= 1m (got ${intent.schedule.kind === "every" ? intent.schedule.every : ""})`);
+    }
+    const nowIso = new Date(nowMs).toISOString();
+    return {
+        version: 1,
+        id: newReminderId(),
+        purpose: intent.purpose,
+        channelId: intent.channelId,
+        continuationToken: intent.continuationToken,
+        target: intent.target,
+        scheduleKind: resolved.kind,
+        scheduleValue: resolved.value,
+        intervalMs: resolved.intervalMs,
+        prompt: intent.prompt,
+        handler: intent.handler,
+        args: intent.args,
+        hasRunHandler: intent.hasRunHandler,
+        hasUntilFn: intent.hasUntilFn,
+        untilPrompt: intent.untilPrompt,
+        busyPolicy: intent.busyPolicy,
+        status: "armed",
+        fireCount: 0,
+        nextFireAtMs: resolved.nextFireAtMs,
+        generation: 0,
+        createdAt: nowIso,
+        updatedAt: nowIso,
+    };
+}
+export function toFireDescriptor(record, claimedAtMs) {
+    return {
+        protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+        id: record.id,
+        fireCount: record.fireCount,
+        generation: recordGeneration(record),
+        purpose: record.purpose,
+        channelId: record.channelId,
+        continuationToken: record.continuationToken,
+        target: record.target,
+        scheduleKind: record.scheduleKind,
+        scheduleValue: record.scheduleValue,
+        intervalMs: record.intervalMs,
+        prompt: record.prompt,
+        handler: record.handler,
+        args: record.args,
+        hasRunHandler: record.hasRunHandler,
+        hasUntilFn: record.hasUntilFn,
+        untilPrompt: record.untilPrompt,
+        busyPolicy: record.busyPolicy,
+        nextFireAtMs: record.nextFireAtMs,
+        claimedAtMs,
+    };
+}
+export function claimFromDescriptor(descriptor) {
+    return {
+        id: descriptor.id,
+        fireCount: descriptor.fireCount,
+        generation: descriptor.generation,
+    };
+}
+function resolveRescheduleMs(reschedule, nowMs) {
+    if (reschedule.delay !== undefined) {
+        return nowMs + parseDuration(reschedule.delay);
+    }
+    if (reschedule.at !== undefined) {
+        const atMs = Date.parse(reschedule.at);
+        if (!Number.isFinite(atMs)) {
+            throw new ReminderValidationError("Invalid reminder reschedule.at");
+        }
+        return atMs;
+    }
+    throw new ReminderValidationError("reminder reschedule requires delay or at");
+}
+/** Next fire time from the record's recurring schedule (CP-owned). */
+export function nextScheduleFireAtMs(record, afterMs) {
+    if (record.scheduleKind === "every" && record.intervalMs !== undefined) {
+        return afterMs + record.intervalMs;
+    }
+    if (record.scheduleKind === "cron") {
+        return nextCronFireMs(record.scheduleValue, afterMs);
+    }
+    throw new ReminderValidationError(`Cannot advance schedule for reminder "${record.id}" (kind=${record.scheduleKind})`);
+}
+export function isOneShotSchedule(kind) {
+    return kind === "delay" || kind === "at";
+}
+/**
+ * Pure CAS apply of a guest outcome onto a reminder record.
+ * Callers persist the returned record when `applied: true`.
+ * Requires `status === "firing"` — an armed record was never claimed.
+ */
+export function applyOutcomeToRecord(record, claim, outcome, nowMs = Date.now()) {
+    var _a;
+    if (record.id !== claim.id) {
+        return { applied: false, reason: "missing", record };
+    }
+    // Prefer duplicate over generation mismatch: a successful prior apply
+    // bumps both fireCount and generation, and retries of (id, fireCount)
+    // must stay idempotent no-ops.
+    if (record.fireCount > claim.fireCount) {
+        return { applied: false, reason: "duplicate", record };
+    }
+    if (record.fireCount < claim.fireCount) {
+        return { applied: false, reason: "stale_fire_count", record };
+    }
+    if (recordGeneration(record) !== claim.generation) {
+        return { applied: false, reason: "stale_generation", record };
+    }
+    // Only a claimed (firing) reminder can accept an outcome.
+    if (record.status !== "firing") {
+        return { applied: false, reason: "not_claimed", record };
+    }
+    const nowIso = new Date(nowMs).toISOString();
+    if (outcome.kind === "retry") {
+        const delayMs = Math.max(REMINDER_CP_MIN_RECURRING_INTERVAL_MS, (_a = outcome.delayMs) !== null && _a !== void 0 ? _a : REMINDER_CP_MIN_RECURRING_INTERVAL_MS);
+        const updated = Object.assign(Object.assign({}, record), { status: "armed", nextFireAtMs: nowMs + delayMs, 
+            // Same fireCount; bump generation so a second apply of the old claim is stale.
+            generation: recordGeneration(record) + 1, updatedAt: nowIso });
+        return { applied: true, record: updated };
+    }
+    if (outcome.kind === "stop") {
+        const updated = Object.assign(Object.assign({}, record), { status: "completed", disarmReason: outcome.reason, fireCount: record.fireCount + 1, generation: recordGeneration(record) + 1, updatedAt: nowIso });
+        return { applied: true, record: updated };
+    }
+    const reschedule = outcome.reschedule;
+    if (reschedule !== undefined) {
+        const nextFireAtMs = resolveRescheduleMs(reschedule, nowMs);
+        const updated = Object.assign(Object.assign({}, record), { status: "armed", fireCount: record.fireCount + 1, nextFireAtMs, scheduleKind: reschedule.delay !== undefined ? "delay" : "at", scheduleValue: reschedule.delay !== undefined
+                ? String(reschedule.delay)
+                : String(reschedule.at), intervalMs: undefined, generation: recordGeneration(record) + 1, updatedAt: nowIso });
+        return { applied: true, record: updated };
+    }
+    if (isOneShotSchedule(record.scheduleKind)) {
+        const updated = Object.assign(Object.assign({}, record), { status: "completed", disarmReason: outcome.kind === "skipped" ? "skipped_one_shot" : "one_shot_complete", fireCount: record.fireCount + 1, generation: recordGeneration(record) + 1, updatedAt: nowIso });
+        return { applied: true, record: updated };
+    }
+    const nextFireAtMs = nextScheduleFireAtMs(record, nowMs);
+    const updated = Object.assign(Object.assign({}, record), { status: "armed", fireCount: record.fireCount + 1, nextFireAtMs, generation: recordGeneration(record) + 1, updatedAt: nowIso });
+    return { applied: true, record: updated };
+}

package/dist/internal/reminder-runner.d.ts

@@ -1,29 +1,63 @@
 /**
  * Per-session reminder runner: durable wake subscriptions with
- * prompt XOR run, every/cron/delay/at schedules, and until as
- * function XOR prompt.
+ * prompt XOR named handler XOR run, every/cron/delay/at schedules, and
+ * until as function XOR prompt.
  */
-import type { ReminderCreateInput, ReminderInfo } from "../types.js";
+import type { DiscoveredReminder, ReminderCreateInput, ReminderInfo, ReminderStatus } from "../types.js";
 import type { PlatformTimers } from "./platform-timers.js";
-import type { ReminderRecord } from "./reminder-store.js";
+import { type ReminderControlPlane, type ReminderExecutionOutcome, type ReminderFireDescriptor } from "./reminder-control-plane-protocol.js";
 import { type SessionEngine } from "./session-engine.js";
 export { ReminderValidationError } from "./reminder-schedule.js";
+/** Max UTF-8 byte length of `JSON.stringify(args)` on named-handler create. */
+export declare const REMINDER_ARGS_MAX_BYTES: number;
 export declare class UnknownReminderError extends Error {
     readonly availableReminderIds: string[];
     constructor(reminderId: string, availableReminderIds: string[]);
 }
+export interface ReminderRunnerOptions {
+    /** Discovered `agent/reminders/*` handlers, keyed by module stem. */
+    namedHandlers?: readonly DiscoveredReminder[];
+    /**
+     * Architecture v2: reject anonymous `run` and function `until` at create
+     * (named `handler` + prompt remain), whether local or hosted.
+     */
+    rejectAnonymousHandlers?: boolean;
+    /**
+     * When set (local self-hosted architecture v2), create/cancel/rekey go
+     * through the control-plane protocol and fires are guest executions of
+     * immutable descriptors.
+     */
+    controlPlane?: ReminderControlPlane;
+    /** Agent architecture; used with {@link controlPlane} for v2 protocol path. */
+    architecture?: "v1" | "v2";
+}
+/**
+ * Server wiring for {@link ReminderRunnerOptions.rejectAnonymousHandlers}:
+ * architecture v2 always rejects anonymous run/until (local or hosted).
+ */
+export declare function rejectAnonymousReminderHandlers(options: {
+    noControlPlane?: boolean;
+    architecture?: string;
+}): boolean;
 export declare class ReminderRunner {
     private readonly engine;
     private readonly logger;
     private readonly platformTimers?;
     private readonly records;
     private readonly handlers;
+    private readonly namedHandlers;
+    private readonly namedHandlerNames;
     private readonly timers;
     private readonly firing;
     /** Single-flight idle gates keyed by `channelId:continuationToken`. */
     private readonly idleGates;
     private started;
-    constructor(engine: SessionEngine, logger?: (line: string) => void, platformTimers?: PlatformTimers | undefined);
+    private readonly rejectAnonymousHandlers;
+    private readonly controlPlane;
+    private readonly architecture;
+    constructor(engine: SessionEngine, logger?: (line: string) => void, platformTimers?: PlatformTimers | undefined, options?: ReminderRunnerOptions);
+    /** True when create/cancel/rekey/fire go through the CP protocol. */
+    private get usesControlPlaneProtocol();
     /**
      * Load reminder documents from the control plane into memory. Does not
      * arm in-process timers — the CP owns clocks.
@@ -37,7 +71,7 @@ export declare class ReminderRunner {
     stop(): void;
     create(input: ReminderCreateInput): Promise<ReminderInfo>;
     list(filter?: {
-        status?: ReminderRecord["status"];
+        status?: ReminderStatus;
         purpose?: string;
         continuationToken?: string;
     }): Promise<ReminderInfo[]>;
@@ -59,8 +93,16 @@ export declare class ReminderRunner {
         outcome: "fired" | "noop";
         reason?: string;
     }>;
+    /**
+     * Architecture v2 / CP protocol guest entrypoint: execute an immutable fire
+     * descriptor and return an outcome. Does not mint ids or mutate
+     * authoritative status/fireCount — the control plane applies the outcome.
+     */
+    executeFire(descriptor: ReminderFireDescriptor): Promise<ReminderExecutionOutcome>;
+    private recordFromDescriptor;
     private armTimer;
     private clearTimer;
+    private resolveNamedHandler;
     private fire;
     private isSessionBusy;
     private whenSessionIdle;
@@ -70,6 +112,14 @@ export declare class ReminderRunner {
      */
     private resolveFollowupAuth;
     private deliverPrompt;
+    /**
+     * Join the reminder's existing session. Control-plane (`/v2`) channels
+     * refuse authored `continuationToken`; pass the stored key as
+     * {@link EngineSendOptions.mailboxContinuation} so the engine reuses the
+     * CP-selected identity without channel admission.
+     */
+    private followupSendOptions;
+    private channelUsesControlPlaneContinuation;
     private sendFollowup;
     private buildFireContext;
     private buildUntilContext;

package/dist/internal/reminder-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reminder-runner.d.ts","sourceRoot":"","sources":["../../src/internal/reminder-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"reminder-runner.d.ts","sourceRoot":"","sources":["../../src/internal/reminder-runner.ts"],"names":[],"mappings":"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"}