@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/plannedMessageManager/filterPlannedMessages.ts

@@ -0,0 +1,191 @@
+import type {
+    PlannedMessageManagerLastRunFilter,
+    PlannedMessageManagerRecord,
+    PlannedMessageManagerRecurrenceFilter,
+    PlannedMessageManagerView,
+} from '../plannedMessagesAdmin';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * Stages shown by each planned-message manager view.
+ *
+ * This is the single place deciding what "active", "finished",... mean, so the tabs, the counters
+ * shown on them, and the listed rows can never describe different sets of planned messages.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const PLANNED_MESSAGE_LIFECYCLES_BY_VIEW: Record<
+    PlannedMessageManagerView,
+    ReadonlyArray<PlannedMessageLifecycle>
+> = {
+    active: ['ONGOING', 'SCHEDULED', 'NOT_STARTED', 'PAUSED'],
+    scheduled: ['SCHEDULED'],
+    'not-started': ['NOT_STARTED'],
+    ongoing: ['ONGOING'],
+    paused: ['PAUSED'],
+    finished: ['CANCELLED', 'ENDED', 'FAILED'],
+    all: ['ONGOING', 'SCHEDULED', 'NOT_STARTED', 'PAUSED', 'CANCELLED', 'ENDED', 'FAILED'],
+};
+
+/**
+ * Age of the newest wake-up still matching each last-run filter, in milliseconds.
+ *
+ * @private constant of `filterPlannedMessages`
+ */
+const PLANNED_MESSAGE_LAST_RUN_WINDOW_MS: Record<'hour' | 'day' | 'week', number> = {
+    hour: 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Filter value meaning "do not narrow by this parameter".
+ *
+ * @private constant of `filterPlannedMessages`
+ */
+const PLANNED_MESSAGE_FILTER_ANY_VALUE = 'all';
+
+/**
+ * Every parameter the planned-message manager can narrow its listing by.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerFilters = {
+    readonly view: PlannedMessageManagerView;
+
+    /**
+     * Permanent id of the agent whose planned messages are listed, or `all` for every agent.
+     */
+    readonly agentPermanentId: string;
+
+    readonly recurrence: PlannedMessageManagerRecurrenceFilter;
+    readonly lastRun: PlannedMessageManagerLastRunFilter;
+
+    /**
+     * Free text matched against the message, its ids, its agent, and its owner.
+     */
+    readonly search: string;
+};
+
+/**
+ * Keeps only the planned messages matching every active filter.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @param filters - Parameters the administrator narrowed the listing by.
+ * @param atDate - Moment the last-run windows are measured from.
+ * @returns Matching planned messages, in the order they were given.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function filterPlannedMessages(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+    filters: PlannedMessageManagerFilters,
+    atDate: Date,
+): Array<PlannedMessageManagerRecord> {
+    const normalizedSearch = filters.search.trim().toLowerCase();
+
+    return plannedMessages.filter(
+        (plannedMessage) =>
+            isPlannedMessageInView(plannedMessage, filters.view) &&
+            isPlannedMessageOfAgent(plannedMessage, filters.agentPermanentId) &&
+            isPlannedMessageOfRecurrence(plannedMessage, filters.recurrence) &&
+            isPlannedMessageLastRunInWindow(plannedMessage, filters.lastRun, atDate) &&
+            isPlannedMessageMatchingSearch(plannedMessage, normalizedSearch),
+    );
+}
+
+/**
+ * Determines whether one planned message belongs to the selected view.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageInView(
+    plannedMessage: PlannedMessageManagerRecord,
+    view: PlannedMessageManagerView,
+): boolean {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW[view].includes(plannedMessage.lifecycle);
+}
+
+/**
+ * Determines whether one planned message belongs to the selected agent.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageOfAgent(plannedMessage: PlannedMessageManagerRecord, agentPermanentId: string): boolean {
+    return (
+        agentPermanentId === PLANNED_MESSAGE_FILTER_ANY_VALUE ||
+        plannedMessage.agentPermanentId.toLowerCase() === agentPermanentId.toLowerCase()
+    );
+}
+
+/**
+ * Determines whether one planned message repeats the selected way.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageOfRecurrence(
+    plannedMessage: PlannedMessageManagerRecord,
+    recurrence: PlannedMessageManagerRecurrenceFilter,
+): boolean {
+    return recurrence === PLANNED_MESSAGE_FILTER_ANY_VALUE || plannedMessage.recurrenceKind === recurrence;
+}
+
+/**
+ * Determines whether one planned message last woke its agent inside the selected window.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageLastRunInWindow(
+    plannedMessage: PlannedMessageManagerRecord,
+    lastRun: PlannedMessageManagerLastRunFilter,
+    atDate: Date,
+): boolean {
+    if (lastRun === PLANNED_MESSAGE_FILTER_ANY_VALUE) {
+        return true;
+    }
+
+    if (plannedMessage.lastFiredAt === null) {
+        return lastRun === 'never';
+    }
+
+    if (lastRun === 'never') {
+        return false;
+    }
+
+    const lastFiredAtTime = Date.parse(plannedMessage.lastFiredAt);
+    if (!Number.isFinite(lastFiredAtTime)) {
+        return false;
+    }
+
+    const lastRunAgeMs = atDate.getTime() - lastFiredAtTime;
+
+    if (lastRun === 'older') {
+        return lastRunAgeMs > PLANNED_MESSAGE_LAST_RUN_WINDOW_MS.week;
+    }
+
+    return lastRunAgeMs <= PLANNED_MESSAGE_LAST_RUN_WINDOW_MS[lastRun];
+}
+
+/**
+ * Determines whether one planned message matches the free-text search.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageMatchingSearch(plannedMessage: PlannedMessageManagerRecord, normalizedSearch: string): boolean {
+    if (normalizedSearch.length === 0) {
+        return true;
+    }
+
+    const searchableValues = [
+        plannedMessage.message,
+        plannedMessage.timeoutId,
+        plannedMessage.agentPermanentId,
+        plannedMessage.agentName,
+        plannedMessage.chatId,
+        plannedMessage.username,
+        String(plannedMessage.userId),
+        plannedMessage.cronExpression,
+    ];
+
+    return searchableValues.some((value) => typeof value === 'string' && value.toLowerCase().includes(normalizedSearch));
+}

package/apps/agents-server/src/utils/plannedMessageManager/getPlannedMessageManagerResponse.ts

@@ -0,0 +1,55 @@
+import { loadAgentNamesByPermanentId, loadUsernamesByUserId } from '../adminEntityLookups';
+import type { PlannedMessageManagerListResponse } from '../plannedMessagesAdmin';
+import { listAllUserChatTimeouts } from '../userChatTimeout';
+import { ensureUserChatTimeoutWorkerBootstrapped } from '../userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
+import { mapPlannedMessageManagerRecord } from './mapPlannedMessageManagerRecord';
+
+/**
+ * Largest number of planned messages the manager loads at once.
+ *
+ * The whole set is sent to the browser so filtering, counting, and sorting all see the same rows;
+ * this cap keeps that promise affordable on a server with a long planning history.
+ *
+ * @private constant of `getPlannedMessageManagerResponse`
+ */
+const MAX_PLANNED_MESSAGE_MANAGER_ITEMS = 1_000;
+
+/**
+ * Builds the admin planned-message manager payload from live durable timeout state.
+ *
+ * Every planned message of every agent and every user of this server is listed, whether it is still
+ * ahead, firing right now, or already over.
+ *
+ * @returns Planned messages with the moment they were read.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function getPlannedMessageManagerResponse(): Promise<PlannedMessageManagerListResponse> {
+    ensureUserChatTimeoutWorkerBootstrapped();
+
+    // Note: One row above the cap is loaded, purely to tell whether anything was left out
+    const loadedPlannedMessages = await listAllUserChatTimeouts({ limit: MAX_PLANNED_MESSAGE_MANAGER_ITEMS + 1 });
+    const hasMore = loadedPlannedMessages.length > MAX_PLANNED_MESSAGE_MANAGER_ITEMS;
+    const plannedMessages = hasMore
+        ? loadedPlannedMessages.slice(0, MAX_PLANNED_MESSAGE_MANAGER_ITEMS)
+        : loadedPlannedMessages;
+
+    const [usernamesById, agentNamesByPermanentId] = await Promise.all([
+        loadUsernamesByUserId(plannedMessages.map((plannedMessage) => plannedMessage.userId)),
+        loadAgentNamesByPermanentId(plannedMessages.map((plannedMessage) => plannedMessage.agentPermanentId)),
+    ]);
+    const generatedAtDate = new Date();
+
+    return {
+        items: plannedMessages.map((plannedMessage) =>
+            mapPlannedMessageManagerRecord({
+                plannedMessage,
+                usernamesById,
+                agentNamesByPermanentId,
+                atDate: generatedAtDate,
+            }),
+        ),
+        generatedAt: generatedAtDate.toISOString(),
+        hasMore,
+    };
+}

package/apps/agents-server/src/utils/plannedMessageManager/isPlannedMessageStillPlanned.ts

@@ -0,0 +1,18 @@
+import { PLANNED_MESSAGE_LIFECYCLES_BY_VIEW } from './filterPlannedMessages';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * Determines whether one planned message is still part of the agent's plans.
+ *
+ * A planned message is still planned while it can wake its agent again — including one held back by a
+ * pause and one whose starting date is still ahead. This is what decides whether it can be re-planned
+ * or cancelled at all, and it is the very same set the `active` view lists.
+ *
+ * @param lifecycle - Stage the planned message is in.
+ * @returns `true` while the planned message is not over.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function isPlannedMessageStillPlanned(lifecycle: PlannedMessageLifecycle): boolean {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW.active.includes(lifecycle);
+}

package/apps/agents-server/src/utils/plannedMessageManager/loadPlannedMessageManagerRecord.ts

@@ -0,0 +1,32 @@
+import { loadAgentNamesByPermanentId, loadUsernamesByUserId } from '../adminEntityLookups';
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { getUserChatTimeoutById } from '../userChatTimeout';
+import { mapPlannedMessageManagerRecord } from './mapPlannedMessageManagerRecord';
+
+/**
+ * Loads one planned message in the shape the admin manager shows it in.
+ *
+ * @param timeoutId - Id of the planned message.
+ * @returns Planned-message manager row, or `null` when there is no such planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadPlannedMessageManagerRecord(timeoutId: string): Promise<PlannedMessageManagerRecord | null> {
+    const plannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!plannedMessage) {
+        return null;
+    }
+
+    const [usernamesById, agentNamesByPermanentId] = await Promise.all([
+        loadUsernamesByUserId([plannedMessage.userId]),
+        loadAgentNamesByPermanentId([plannedMessage.agentPermanentId]),
+    ]);
+
+    return mapPlannedMessageManagerRecord({
+        plannedMessage,
+        usernamesById,
+        agentNamesByPermanentId,
+        atDate: new Date(),
+    });
+}

package/apps/agents-server/src/utils/plannedMessageManager/mapPlannedMessageManagerRecord.ts

@@ -0,0 +1,73 @@
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { isAgentGoalChatId } from '../agentGoalChat/agentGoalChatIdentity';
+import type { UserChatTimeoutRecord } from '../userChatTimeout/UserChatTimeoutRecord';
+import { resolvePlannedMessageEndReason } from './resolvePlannedMessageEndReason';
+import { resolvePlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+import { resolvePlannedMessageRecurrenceKind } from './resolvePlannedMessageRecurrenceKind';
+
+/**
+ * Everything needed to turn one stored timeout into a manager row.
+ *
+ * @private type of `mapPlannedMessageManagerRecord`
+ */
+type MapPlannedMessageManagerRecordOptions = {
+    readonly plannedMessage: UserChatTimeoutRecord;
+    readonly usernamesById: ReadonlyMap<number, string>;
+    readonly agentNamesByPermanentId: ReadonlyMap<string, string | null>;
+
+    /**
+     * Moment the stage of the planned message is judged at.
+     */
+    readonly atDate: Date;
+};
+
+/**
+ * Maps one stored timeout into the row shown by the admin planned-message manager.
+ *
+ * The stage and the ending reason are derived here once, so every later step — filtering, counting,
+ * and rendering — reads the same answer instead of judging the raw columns again.
+ *
+ * @param options - Stored timeout with the names of its agent and owner.
+ * @returns Planned-message manager row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function mapPlannedMessageManagerRecord(
+    options: MapPlannedMessageManagerRecordOptions,
+): PlannedMessageManagerRecord {
+    const { plannedMessage, usernamesById, agentNamesByPermanentId, atDate } = options;
+    const lifecycle = resolvePlannedMessageLifecycle(plannedMessage, atDate);
+
+    return {
+        timeoutId: plannedMessage.timeoutId,
+        status: plannedMessage.status,
+        lifecycle,
+        recurrenceKind: resolvePlannedMessageRecurrenceKind(plannedMessage),
+        endReason: lifecycle === 'ENDED' ? resolvePlannedMessageEndReason(plannedMessage, atDate) : null,
+        message: plannedMessage.message,
+
+        createdAt: plannedMessage.createdAt,
+        updatedAt: plannedMessage.updatedAt,
+        dueAt: plannedMessage.dueAt,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        lastFiredAt: plannedMessage.lastFiredAt,
+        completedAt: plannedMessage.completedAt,
+        cancelRequestedAt: plannedMessage.cancelRequestedAt,
+        pausedAt: plannedMessage.pausedAt,
+
+        recurrenceIntervalMs: plannedMessage.recurrenceIntervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
+        attemptCount: plannedMessage.attemptCount,
+        failureReason: plannedMessage.failureReason,
+
+        userId: plannedMessage.userId,
+        username: usernamesById.get(plannedMessage.userId) ?? null,
+        agentPermanentId: plannedMessage.agentPermanentId,
+        agentName: agentNamesByPermanentId.get(plannedMessage.agentPermanentId) ?? null,
+        chatId: plannedMessage.chatId,
+        isAgentGoalChat: isAgentGoalChatId(plannedMessage.chatId),
+    };
+}

package/apps/agents-server/src/utils/plannedMessageManager/parsePlannedMessageManagerUpdateRequest.ts

@@ -0,0 +1,76 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import type { UpdateManagedPlannedMessageRequest } from './updateManagedPlannedMessage';
+
+/**
+ * Fields one administrator request may carry, in the order they are read.
+ *
+ * @private constant of `parsePlannedMessageManagerUpdateRequest`
+ */
+const PLANNED_MESSAGE_UPDATE_REQUEST_FIELDS = [
+    'message',
+    'milliseconds',
+    'cronExpression',
+    'startsAt',
+    'endsAt',
+    'maxRunCount',
+] as const satisfies ReadonlyArray<keyof UpdateManagedPlannedMessageRequest>;
+
+/**
+ * Parses the untrusted body of one planned-message change request.
+ *
+ * Only the presence of each field is decided here — what a field is allowed to contain stays with the
+ * shared planned-message service, so an administrator and an agent are held to one set of rules.
+ *
+ * @param rawBody - Parsed JSON body of the request.
+ * @returns Requested change, carrying exactly the fields that were really sent.
+ * @throws {ParseError} When the body is not an object, carries no change, or holds an invalid `isPaused`.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function parsePlannedMessageManagerUpdateRequest(rawBody: unknown): UpdateManagedPlannedMessageRequest {
+    if (typeof rawBody !== 'object' || rawBody === null || Array.isArray(rawBody)) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message change.
+
+                - The request body must be a **JSON object** describing the change.
+            `),
+        );
+    }
+
+    const requestBody = rawBody as Record<string, unknown>;
+    const parsedRequest: Record<string, unknown> = {};
+
+    for (const fieldName of PLANNED_MESSAGE_UPDATE_REQUEST_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(requestBody, fieldName)) {
+            parsedRequest[fieldName] = requestBody[fieldName];
+        }
+    }
+
+    if (Object.prototype.hasOwnProperty.call(requestBody, 'isPaused')) {
+        if (typeof requestBody.isPaused !== 'boolean') {
+            throw new ParseError(
+                spaceTrim(`
+                    Invalid planned-message change.
+
+                    - \`isPaused\` must be \`true\` to hold the planned message back, or \`false\` to let it go again.
+                `),
+            );
+        }
+
+        parsedRequest.isPaused = requestBody.isPaused;
+    }
+
+    if (Object.keys(parsedRequest).length === 0) {
+        throw new ParseError(
+            spaceTrim(`
+                Nothing to change in this planned message.
+
+                - Pass at least one of \`cronExpression\`, \`milliseconds\`, \`startsAt\`, \`endsAt\`, \`maxRunCount\`, \`message\`, or \`isPaused\`.
+            `),
+        );
+    }
+
+    return parsedRequest as UpdateManagedPlannedMessageRequest;
+}

package/apps/agents-server/src/utils/plannedMessageManager/resolvePlannedMessageEndReason.ts

@@ -0,0 +1,59 @@
+import { resolvePlannedMessageRecurrenceKind } from './resolvePlannedMessageRecurrenceKind';
+
+/**
+ * Why one planned message stopped waking its agent.
+ *
+ * `null` means the planned message is not over, or that nothing in its own schedule explains the end
+ * — a cancelled or failed message ends for a reason outside its schedule.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageEndReason = 'MAX_RUNS_REACHED' | 'ENDING_DATE_PASSED' | 'SINGLE_RUN_DONE' | null;
+
+/**
+ * Stored fields deciding why one planned message is over.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageEndReasonInput = {
+    readonly recurrenceIntervalMs: number | null;
+    readonly cronExpression: string | null;
+    readonly endsAt: string | null;
+    readonly maxRunCount: number | null;
+    readonly runCount: number;
+};
+
+/**
+ * Resolves why one finished planned message will never wake its agent again.
+ *
+ * The bounds are read in the same order the scheduler applies them, so the manager explains an ended
+ * plan exactly the way it really ended.
+ *
+ * @param plannedMessage - Stored planned message that is already over.
+ * @param atDate - Moment the ending is judged at.
+ * @returns Reason the plan is over, or `null` when its schedule does not explain the end.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageEndReason(
+    plannedMessage: PlannedMessageEndReasonInput,
+    atDate: Date,
+): PlannedMessageEndReason {
+    if (plannedMessage.maxRunCount !== null && plannedMessage.runCount >= plannedMessage.maxRunCount) {
+        return 'MAX_RUNS_REACHED';
+    }
+
+    if (plannedMessage.endsAt !== null) {
+        const endsAtTime = Date.parse(plannedMessage.endsAt);
+
+        if (Number.isFinite(endsAtTime) && endsAtTime <= atDate.getTime()) {
+            return 'ENDING_DATE_PASSED';
+        }
+    }
+
+    if (resolvePlannedMessageRecurrenceKind(plannedMessage) === 'ONCE') {
+        return 'SINGLE_RUN_DONE';
+    }
+
+    return null;
+}

package/apps/agents-server/src/utils/plannedMessageManager/resolvePlannedMessageLifecycle.ts

@@ -0,0 +1,99 @@
+import type { UserChatTimeoutStatus } from '../userChatTimeout/UserChatTimeoutRecord';
+
+/**
+ * Stage one planned message is in, as shown by the planned-message manager.
+ *
+ * The stored `UserChatTimeoutStatus` alone cannot answer this: a queued planned message may be
+ * waiting for its own starting date, may be paused, or may already have a cancellation on its way,
+ * and all three look like `QUEUED` in the database.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageLifecycle =
+    | 'ONGOING'
+    | 'SCHEDULED'
+    | 'NOT_STARTED'
+    | 'PAUSED'
+    | 'CANCELLED'
+    | 'ENDED'
+    | 'FAILED';
+
+/**
+ * Stored fields needed to tell which stage one planned message is in.
+ *
+ * Both a durable timeout row and one manager row satisfy this shape, so the very same rule decides
+ * the stage on the server and in the browser.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageLifecycleInput = {
+    readonly status: UserChatTimeoutStatus;
+    readonly pausedAt: string | null;
+    readonly cancelRequestedAt: string | null;
+    readonly startsAt: string | null;
+};
+
+/**
+ * Resolves the stage one planned message is in.
+ *
+ * @param plannedMessage - Stored planned message.
+ * @param atDate - Moment the stage is judged at.
+ * @returns Stage of the planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageLifecycle(
+    plannedMessage: PlannedMessageLifecycleInput,
+    atDate: Date,
+): PlannedMessageLifecycle {
+    if (plannedMessage.status === 'RUNNING') {
+        return 'ONGOING';
+    }
+
+    if (plannedMessage.status === 'FAILED') {
+        return 'FAILED';
+    }
+
+    if (plannedMessage.status === 'CANCELLED') {
+        return 'CANCELLED';
+    }
+
+    if (plannedMessage.status === 'COMPLETED') {
+        return 'ENDED';
+    }
+
+    // Note: A cancellation is requested on the row first and only turned into `CANCELLED` by the
+    //       worker, so a queued row carrying that request is already on its way out
+    if (plannedMessage.cancelRequestedAt !== null) {
+        return 'CANCELLED';
+    }
+
+    if (plannedMessage.pausedAt !== null) {
+        return 'PAUSED';
+    }
+
+    if (isPlannedMessageWaitingForStartingDate(plannedMessage.startsAt, atDate)) {
+        return 'NOT_STARTED';
+    }
+
+    return 'SCHEDULED';
+}
+
+/**
+ * Determines whether one planned message may not wake its agent yet because its window has not opened.
+ *
+ * @param startsAt - Moment before which the planned message never wakes the agent.
+ * @param atDate - Moment the stage is judged at.
+ * @returns `true` while the starting date is still ahead.
+ *
+ * @private function of `resolvePlannedMessageLifecycle`
+ */
+function isPlannedMessageWaitingForStartingDate(startsAt: string | null, atDate: Date): boolean {
+    if (startsAt === null) {
+        return false;
+    }
+
+    const startsAtTime = Date.parse(startsAt);
+
+    return Number.isFinite(startsAtTime) && startsAtTime > atDate.getTime();
+}

package/apps/agents-server/src/utils/plannedMessageManager/resolvePlannedMessageRecurrenceKind.ts

@@ -0,0 +1,40 @@
+/**
+ * How often one planned message wakes its agent.
+ *
+ * A planned message follows exactly one recurrence rule, so these three kinds are exhaustive.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageRecurrenceKind = 'ONCE' | 'INTERVAL' | 'CRON';
+
+/**
+ * Stored fields deciding how often one planned message repeats.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageRecurrenceInput = {
+    readonly recurrenceIntervalMs: number | null;
+    readonly cronExpression: string | null;
+};
+
+/**
+ * Resolves how often one planned message wakes its agent.
+ *
+ * @param plannedMessage - Stored planned message.
+ * @returns Recurrence kind of the planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageRecurrenceKind(
+    plannedMessage: PlannedMessageRecurrenceInput,
+): PlannedMessageRecurrenceKind {
+    if (plannedMessage.cronExpression) {
+        return 'CRON';
+    }
+
+    if (plannedMessage.recurrenceIntervalMs) {
+        return 'INTERVAL';
+    }
+
+    return 'ONCE';
+}