@promptbook/cli 0.114.0-13 → 0.114.0-18

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

@@ -0,0 +1,56 @@
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+
+/**
+ * One agent offered by the planned-message agent filter.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageAgentOption = {
+    readonly agentPermanentId: string;
+    readonly agentName: string | null;
+    readonly plannedMessageCount: number;
+};
+
+/**
+ * Collects the agents that really have planned messages, for the agent filter.
+ *
+ * Only agents present in the listing are offered, so the filter can never select an empty result.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @returns Agents sorted by their displayed name.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function collectPlannedMessageAgentOptions(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+): Array<PlannedMessageAgentOption> {
+    const optionsByAgentPermanentId = new Map<string, PlannedMessageAgentOption>();
+
+    for (const plannedMessage of plannedMessages) {
+        const existingOption = optionsByAgentPermanentId.get(plannedMessage.agentPermanentId);
+
+        optionsByAgentPermanentId.set(plannedMessage.agentPermanentId, {
+            agentPermanentId: plannedMessage.agentPermanentId,
+            agentName: existingOption?.agentName ?? plannedMessage.agentName,
+            plannedMessageCount: (existingOption?.plannedMessageCount ?? 0) + 1,
+        });
+    }
+
+    return [...optionsByAgentPermanentId.values()].sort((leftOption, rightOption) =>
+        resolvePlannedMessageAgentOptionLabel(leftOption).localeCompare(
+            resolvePlannedMessageAgentOptionLabel(rightOption),
+        ),
+    );
+}
+
+/**
+ * Resolves the label of one agent filter option.
+ *
+ * @param option - Agent offered by the filter.
+ * @returns Agent name, falling back to its permanent id.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageAgentOptionLabel(option: PlannedMessageAgentOption): string {
+    return option.agentName || option.agentPermanentId;
+}

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

@@ -0,0 +1,104 @@
+import type { PlannedMessageManagerRecord, PlannedMessageManagerView } from '../plannedMessagesAdmin';
+import { PLANNED_MESSAGE_LIFECYCLES_BY_VIEW } from './filterPlannedMessages';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * How many planned messages stand in each stage right now.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerCounters = {
+    readonly countByLifecycle: Record<PlannedMessageLifecycle, number>;
+    readonly totalCount: number;
+
+    /**
+     * Earliest moment any planned message is going to wake its agent, or `null` when none will.
+     */
+    readonly nextDueAt: string | null;
+};
+
+/**
+ * Stages that still have a wake-up ahead of them.
+ *
+ * @private constant of `createPlannedMessageManagerCounters`
+ */
+const UPCOMING_PLANNED_MESSAGE_LIFECYCLES: ReadonlyArray<PlannedMessageLifecycle> = ['SCHEDULED', 'NOT_STARTED'];
+
+/**
+ * Counts the planned messages of each stage and finds the next wake-up ahead.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @returns Counters rendered above the planned-message table.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function createPlannedMessageManagerCounters(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+): PlannedMessageManagerCounters {
+    const countByLifecycle: Record<PlannedMessageLifecycle, number> = {
+        ONGOING: 0,
+        SCHEDULED: 0,
+        NOT_STARTED: 0,
+        PAUSED: 0,
+        CANCELLED: 0,
+        ENDED: 0,
+        FAILED: 0,
+    };
+    let nextDueAt: string | null = null;
+
+    for (const plannedMessage of plannedMessages) {
+        countByLifecycle[plannedMessage.lifecycle] += 1;
+
+        if (UPCOMING_PLANNED_MESSAGE_LIFECYCLES.includes(plannedMessage.lifecycle)) {
+            nextDueAt = resolveEarlierDate(nextDueAt, plannedMessage.dueAt);
+        }
+    }
+
+    return {
+        countByLifecycle,
+        totalCount: plannedMessages.length,
+        nextDueAt,
+    };
+}
+
+/**
+ * Counts the planned messages one manager view lists.
+ *
+ * @param counters - Counters of every stage.
+ * @param view - View whose size is asked for.
+ * @returns Number of planned messages the view lists before any other filter narrows it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageManagerViewCount(
+    counters: PlannedMessageManagerCounters,
+    view: PlannedMessageManagerView,
+): number {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW[view].reduce(
+        (viewCount, lifecycle) => viewCount + counters.countByLifecycle[lifecycle],
+        0,
+    );
+}
+
+/**
+ * Keeps whichever of two moments comes first.
+ *
+ * @param currentDate - Earliest moment found so far, or `null`.
+ * @param candidateDate - Moment being considered.
+ * @returns Earlier of the two moments.
+ *
+ * @private function of `createPlannedMessageManagerCounters`
+ */
+function resolveEarlierDate(currentDate: string | null, candidateDate: string): string | null {
+    const candidateTime = Date.parse(candidateDate);
+
+    if (!Number.isFinite(candidateTime)) {
+        return currentDate;
+    }
+
+    if (currentDate === null) {
+        return candidateDate;
+    }
+
+    return candidateTime < Date.parse(currentDate) ? candidateDate : currentDate;
+}

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