@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/app/admin/planned-messages/plannedMessageEditForm.ts

@@ -0,0 +1,186 @@
+'use client';
+
+import type { PlannedMessageRecurrenceKind } from '@/src/utils/plannedMessageManager/resolvePlannedMessageRecurrenceKind';
+import type { PlannedMessageManagerRecord, PlannedMessageManagerUpdatePayload } from '@/src/utils/plannedMessagesAdmin';
+
+/**
+ * Unit one repeat interval is edited in.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export type PlannedMessageIntervalUnit = 'minutes' | 'hours' | 'days';
+
+/**
+ * Length of each editable interval unit, in milliseconds.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+const PLANNED_MESSAGE_INTERVAL_UNIT_MS: Record<PlannedMessageIntervalUnit, number> = {
+    minutes: 60_000,
+    hours: 60 * 60_000,
+    days: 24 * 60 * 60_000,
+};
+
+/**
+ * Units tried when showing a stored interval, from the longest to the shortest.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+const PLANNED_MESSAGE_INTERVAL_UNITS_BY_LENGTH: ReadonlyArray<PlannedMessageIntervalUnit> = [
+    'days',
+    'hours',
+    'minutes',
+];
+
+/**
+ * Editable form of one planned message.
+ *
+ * Every field is kept as the text the administrator typed, so what is validated is exactly what was
+ * entered — the shared planned-message service is the one place saying whether it is allowed.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export type PlannedMessageEditForm = {
+    readonly message: string;
+    readonly recurrenceKind: PlannedMessageRecurrenceKind;
+    readonly intervalValue: string;
+    readonly intervalUnit: PlannedMessageIntervalUnit;
+    readonly cronExpression: string;
+    readonly startsAtLocal: string;
+    readonly endsAtLocal: string;
+    readonly maxRunCount: string;
+};
+
+/**
+ * Fills the edit form with the plan one planned message has today.
+ *
+ * @param plannedMessage - Planned message being edited.
+ * @returns Form describing its current plan.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export function createPlannedMessageEditForm(plannedMessage: PlannedMessageManagerRecord): PlannedMessageEditForm {
+    const interval = resolvePlannedMessageIntervalFields(plannedMessage.recurrenceIntervalMs);
+
+    return {
+        message: plannedMessage.message || '',
+        recurrenceKind: plannedMessage.recurrenceKind,
+        intervalValue: interval.value,
+        intervalUnit: interval.unit,
+        cronExpression: plannedMessage.cronExpression || '',
+        startsAtLocal: formatIsoAsDateTimeLocalValue(plannedMessage.startsAt),
+        endsAtLocal: formatIsoAsDateTimeLocalValue(plannedMessage.endsAt),
+        maxRunCount: plannedMessage.maxRunCount === null ? '' : String(plannedMessage.maxRunCount),
+    };
+}
+
+/**
+ * Turns the edit form into the change sent to the server.
+ *
+ * The whole plan is sent, not only what changed, so an emptied field really removes its bound instead
+ * of silently keeping the stored one.
+ *
+ * @param form - Form as the administrator filled it in.
+ * @returns Requested change.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export function createPlannedMessageUpdatePayload(form: PlannedMessageEditForm): PlannedMessageManagerUpdatePayload {
+    return {
+        message: form.message.trim(),
+        milliseconds: form.recurrenceKind === 'INTERVAL' ? resolvePlannedMessageIntervalMs(form) : null,
+        cronExpression: form.recurrenceKind === 'CRON' ? form.cronExpression.trim() : null,
+        startsAt: parseDateTimeLocalValueAsIso(form.startsAtLocal),
+        endsAt: parseDateTimeLocalValueAsIso(form.endsAtLocal),
+        maxRunCount: form.maxRunCount.trim() === '' ? null : Number(form.maxRunCount),
+    };
+}
+
+/**
+ * Resolves the repeat interval described by the form, in milliseconds.
+ *
+ * @param form - Form as the administrator filled it in.
+ * @returns Interval in milliseconds, or `null` when nothing usable was typed.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+function resolvePlannedMessageIntervalMs(form: PlannedMessageEditForm): number | null {
+    const intervalValue = Number(form.intervalValue);
+
+    if (!Number.isFinite(intervalValue)) {
+        return null;
+    }
+
+    return Math.floor(intervalValue * PLANNED_MESSAGE_INTERVAL_UNIT_MS[form.intervalUnit]);
+}
+
+/**
+ * Splits one stored interval into the longest unit that describes it as a whole number.
+ *
+ * @param recurrenceIntervalMs - Stored repeat interval.
+ * @returns Interval value and unit shown in the form.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+function resolvePlannedMessageIntervalFields(recurrenceIntervalMs: number | null): {
+    value: string;
+    unit: PlannedMessageIntervalUnit;
+} {
+    if (!recurrenceIntervalMs) {
+        return { value: '', unit: 'minutes' };
+    }
+
+    for (const unit of PLANNED_MESSAGE_INTERVAL_UNITS_BY_LENGTH) {
+        const unitMs = PLANNED_MESSAGE_INTERVAL_UNIT_MS[unit];
+
+        if (recurrenceIntervalMs % unitMs === 0) {
+            return { value: String(recurrenceIntervalMs / unitMs), unit };
+        }
+    }
+
+    return { value: String(recurrenceIntervalMs / PLANNED_MESSAGE_INTERVAL_UNIT_MS.minutes), unit: 'minutes' };
+}
+
+/**
+ * Formats one stored moment for a `datetime-local` input, in the administrator's own time zone.
+ *
+ * @param isoDate - Stored moment, or `null`.
+ * @returns Local `YYYY-MM-DDTHH:mm` text, or an empty string.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export function formatIsoAsDateTimeLocalValue(isoDate: string | null): string {
+    if (isoDate === null) {
+        return '';
+    }
+
+    const parsedDate = new Date(isoDate);
+
+    if (Number.isNaN(parsedDate.getTime())) {
+        return '';
+    }
+
+    const localDate = new Date(parsedDate.getTime() - parsedDate.getTimezoneOffset() * 60_000);
+
+    return localDate.toISOString().slice(0, 16);
+}
+
+/**
+ * Reads one `datetime-local` input back as a stored moment.
+ *
+ * @param dateTimeLocalValue - Local `YYYY-MM-DDTHH:mm` text.
+ * @returns ISO moment, or `null` when the field was left empty.
+ *
+ * @private function of PlannedMessageManagerEditDialog
+ */
+export function parseDateTimeLocalValueAsIso(dateTimeLocalValue: string): string | null {
+    const trimmedValue = dateTimeLocalValue.trim();
+
+    if (trimmedValue === '') {
+        return null;
+    }
+
+    const parsedDate = new Date(trimmedValue);
+
+    return Number.isNaN(parsedDate.getTime()) ? trimmedValue : parsedDate.toISOString();
+}

package/apps/agents-server/src/app/admin/planned-messages/plannedMessageManagerDialogs.ts

@@ -0,0 +1,46 @@
+'use client';
+
+import { showAlert, showConfirm } from '@/src/components/AsyncDialogs/asyncDialogs';
+import type { PlannedMessageManagerRecord } from '@/src/utils/plannedMessagesAdmin';
+import { spaceTrim } from 'spacetrim';
+import { resolvePlannedMessageText } from './plannedMessageManagerPresentation';
+
+/**
+ * Asks the administrator to confirm cancelling one planned message.
+ *
+ * @param plannedMessage - Planned message about to be cancelled.
+ * @returns `true` when the administrator confirmed.
+ *
+ * @private shared dialog flow of the admin planned-message manager
+ */
+export function confirmCancelPlannedMessage(plannedMessage: PlannedMessageManagerRecord): Promise<boolean> {
+    return showConfirm({
+        title: 'Cancel planned message',
+        message: spaceTrim(
+            (block) => `
+                Cancel this planned message of "${plannedMessage.agentName || plannedMessage.agentPermanentId}"?
+
+                ${block(resolvePlannedMessageText(plannedMessage))}
+
+                It never wakes the agent again, and stays listed as cancelled.
+            `,
+        ),
+        confirmLabel: 'Cancel planned message',
+        cancelLabel: 'Keep it',
+    }).catch(() => false);
+}
+
+/**
+ * Surfaces a failed planned-message action to the administrator.
+ *
+ * @param title - Short title naming what failed.
+ * @param error - Error thrown by the action.
+ *
+ * @private shared dialog flow of the admin planned-message manager
+ */
+export async function showPlannedMessageActionFailure(title: string, error: unknown): Promise<void> {
+    await showAlert({
+        title,
+        message: error instanceof Error ? error.message : 'The planned-message action failed.',
+    }).catch(() => undefined);
+}

package/apps/agents-server/src/app/admin/planned-messages/plannedMessageManagerPresentation.tsx

@@ -0,0 +1,188 @@
+'use client';
+
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import type { PlannedMessageEndReason } from '@/src/utils/plannedMessageManager/resolvePlannedMessageEndReason';
+import type { PlannedMessageLifecycle } from '@/src/utils/plannedMessageManager/resolvePlannedMessageLifecycle';
+import type { PlannedMessageManagerRecord } from '@/src/utils/plannedMessagesAdmin';
+import { formatServerLanguageHumanReadableDate } from '@/src/utils/localization/formatServerLanguageHumanReadableDate';
+import { describeAgentPlannedMessageSchedule } from '../../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
+import { formatTimeoutDurationHuman } from '../../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+
+/**
+ * Human label of each planned-message stage.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export const PLANNED_MESSAGE_LIFECYCLE_LABELS: Record<PlannedMessageLifecycle, string> = {
+    ONGOING: 'Ongoing',
+    SCHEDULED: 'Scheduled',
+    NOT_STARTED: 'Not started',
+    PAUSED: 'Paused',
+    CANCELLED: 'Cancelled',
+    ENDED: 'Ended',
+    FAILED: 'Failed',
+};
+
+/**
+ * What each planned-message stage means, shown as the badge tooltip.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+const PLANNED_MESSAGE_LIFECYCLE_TITLES: Record<PlannedMessageLifecycle, string> = {
+    ONGOING: 'Waking its agent right now',
+    SCHEDULED: 'Waiting for its next wake-up',
+    NOT_STARTED: 'Planned, but its starting date is still ahead',
+    PAUSED: 'Held back, so it does not wake its agent until it is resumed',
+    CANCELLED: 'Cancelled, so it never wakes its agent again',
+    ENDED: 'Over, because its plan ran out',
+    FAILED: 'Stopped after its wake-up could not be delivered',
+};
+
+/**
+ * Badge color classes of each planned-message stage.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+const PLANNED_MESSAGE_LIFECYCLE_CLASS_MAP: Record<PlannedMessageLifecycle, string> = {
+    ONGOING: 'border-blue-200 bg-blue-50 text-blue-700',
+    SCHEDULED: 'border-slate-200 bg-slate-50 text-slate-700',
+    NOT_STARTED: 'border-indigo-200 bg-indigo-50 text-indigo-700',
+    PAUSED: 'border-orange-200 bg-orange-50 text-orange-700',
+    CANCELLED: 'border-gray-200 bg-gray-100 text-gray-700',
+    ENDED: 'border-emerald-200 bg-emerald-50 text-emerald-700',
+    FAILED: 'border-rose-200 bg-rose-50 text-rose-700',
+};
+
+/**
+ * Human explanation of why one planned message is over.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+const PLANNED_MESSAGE_END_REASON_LABELS: Record<NonNullable<PlannedMessageEndReason>, string> = {
+    MAX_RUNS_REACHED: 'all planned runs done',
+    ENDING_DATE_PASSED: 'ending date passed',
+    SINGLE_RUN_DONE: 'single wake-up done',
+};
+
+/**
+ * Compact badge naming the stage one planned message is in.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function PlannedMessageLifecycleBadge({ lifecycle }: { lifecycle: PlannedMessageLifecycle }) {
+    return (
+        <span
+            className={`rounded-full border px-2 py-0.5 text-[11px] font-semibold ${PLANNED_MESSAGE_LIFECYCLE_CLASS_MAP[lifecycle]}`}
+            title={PLANNED_MESSAGE_LIFECYCLE_TITLES[lifecycle]}
+        >
+            {PLANNED_MESSAGE_LIFECYCLE_LABELS[lifecycle]}
+        </span>
+    );
+}
+
+/**
+ * Compact badge marking the planned messages an agent wrote for itself in its goal chat.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function PlannedMessageGoalChatBadge({ plannedMessage }: { plannedMessage: PlannedMessageManagerRecord }) {
+    if (!plannedMessage.isAgentGoalChat) {
+        return null;
+    }
+
+    return (
+        <span
+            className="rounded-full border border-indigo-200 bg-indigo-50 px-2 py-0.5 text-[11px] font-semibold text-indigo-700"
+            title="Planned by the agent itself in its goal chat, not by a user"
+        >
+            Goal chat
+        </span>
+    );
+}
+
+/**
+ * Formats how often one planned message wakes its agent.
+ *
+ * @param plannedMessage - Planned message being described.
+ * @returns Short frequency text such as `Every 5 minutes`.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function formatPlannedMessageFrequency(plannedMessage: PlannedMessageManagerRecord): string {
+    if (plannedMessage.recurrenceKind === 'CRON') {
+        return `Cron ${plannedMessage.cronExpression}`;
+    }
+
+    if (plannedMessage.recurrenceKind === 'INTERVAL') {
+        return `Every ${formatTimeoutDurationHuman(plannedMessage.recurrenceIntervalMs || 0)}`;
+    }
+
+    return 'Once';
+}
+
+/**
+ * Describes the whole plan of one planned message in one sentence.
+ *
+ * The wording comes from the very same helper the agent itself is told its plan with, so the manager
+ * and the agent never describe one plan in two different ways.
+ *
+ * @param plannedMessage - Planned message being described.
+ * @returns Sentence fragment describing the plan.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function describePlannedMessagePlan(plannedMessage: PlannedMessageManagerRecord): string {
+    return describeAgentPlannedMessageSchedule({
+        intervalMs: plannedMessage.recurrenceIntervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
+        dueAt: plannedMessage.dueAt,
+    });
+}
+
+/**
+ * Formats why one planned message is over.
+ *
+ * @param endReason - Reason the plan is over.
+ * @returns Short explanation, or `null` when the plan does not explain its own end.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function formatPlannedMessageEndReason(endReason: PlannedMessageEndReason): string | null {
+    return endReason === null ? null : PLANNED_MESSAGE_END_REASON_LABELS[endReason];
+}
+
+/**
+ * Formats how many wake-ups one planned message already did, out of how many it may do.
+ *
+ * @param plannedMessage - Planned message being described.
+ * @returns Run counter such as `2 / 10`.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function formatPlannedMessageRunCount(plannedMessage: PlannedMessageManagerRecord): string {
+    return plannedMessage.maxRunCount === null
+        ? String(plannedMessage.runCount)
+        : `${plannedMessage.runCount} / ${plannedMessage.maxRunCount}`;
+}
+
+/**
+ * Formats one timestamp for compact planned-message display.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function formatPlannedMessageDateTime(value: string | null, language: ServerLanguageCode): string {
+    return formatServerLanguageHumanReadableDate(value, language, { fallbackLabel: '-' });
+}
+
+/**
+ * Resolves the text shown for one planned message that has no message of its own.
+ *
+ * @private shared presentation of the admin planned-message manager
+ */
+export function resolvePlannedMessageText(plannedMessage: PlannedMessageManagerRecord): string {
+    return plannedMessage.message || 'Planned wake-up without a message';
+}

package/apps/agents-server/src/app/admin/planned-messages/resolvePlannedMessageSortValue.ts

@@ -0,0 +1,115 @@
+'use client';
+
+import { isPlannedMessageStillPlanned } from '@/src/utils/plannedMessageManager/isPlannedMessageStillPlanned';
+import type { PlannedMessageLifecycle } from '@/src/utils/plannedMessageManager/resolvePlannedMessageLifecycle';
+import type { PlannedMessageManagerRecord, PlannedMessageManagerSortField } from '@/src/utils/plannedMessagesAdmin';
+import type { AdminTableSortableValue, AdminTableSortOrder } from '../_components/adminTableSorting';
+import { resolvePlannedMessageText } from './plannedMessageManagerPresentation';
+
+/**
+ * Order the stages are sorted in, from the most immediate to the most finished.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+const PLANNED_MESSAGE_LIFECYCLE_SORT_RANK: Record<PlannedMessageLifecycle, number> = {
+    ONGOING: 0,
+    SCHEDULED: 1,
+    NOT_STARTED: 2,
+    PAUSED: 3,
+    CANCELLED: 4,
+    ENDED: 5,
+    FAILED: 6,
+};
+
+/**
+ * Sort value standing for a planned message that repeats on a cron.
+ *
+ * A cron cadence cannot be compared with a fixed interval without evaluating it, so cron-driven
+ * messages are sorted after every fixed interval but before the ones that never repeat.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+const CRON_PLANNED_MESSAGE_FREQUENCY_SORT_VALUE = Number.MAX_SAFE_INTEGER - 1;
+
+/**
+ * Sort value standing for a planned message that wakes its agent exactly once.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+const SINGLE_RUN_PLANNED_MESSAGE_FREQUENCY_SORT_VALUE = Number.MAX_SAFE_INTEGER;
+
+/**
+ * Resolves the comparable value of one planned message for the active sort column.
+ *
+ * Sorting by frequency puts the most frequently repeating planned messages first, because that is the
+ * order an administrator looks for when asking which plan is costing the most wake-ups.
+ *
+ * @param plannedMessage - Planned message being sorted.
+ * @param sortBy - Column the table is sorted by.
+ * @returns Comparable value of the planned message.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export function resolvePlannedMessageSortValue(
+    plannedMessage: PlannedMessageManagerRecord,
+    sortBy: PlannedMessageManagerSortField,
+): AdminTableSortableValue {
+    if (sortBy === 'plannedMessage') {
+        return resolvePlannedMessageText(plannedMessage);
+    }
+
+    if (sortBy === 'agent') {
+        return plannedMessage.agentName || plannedMessage.agentPermanentId;
+    }
+
+    if (sortBy === 'frequency') {
+        return resolvePlannedMessageFrequencySortValue(plannedMessage);
+    }
+
+    if (sortBy === 'nextRun') {
+        // Note: A planned message that is over has no wake-up ahead, so it sorts after every one that has
+        return isPlannedMessageStillPlanned(plannedMessage.lifecycle) ? new Date(plannedMessage.dueAt) : null;
+    }
+
+    if (sortBy === 'lastRun') {
+        return plannedMessage.lastFiredAt === null ? null : new Date(plannedMessage.lastFiredAt);
+    }
+
+    if (sortBy === 'runs') {
+        return plannedMessage.runCount;
+    }
+
+    return PLANNED_MESSAGE_LIFECYCLE_SORT_RANK[plannedMessage.lifecycle];
+}
+
+/**
+ * Resolves the initial direction used when switching planned-message sort columns.
+ *
+ * @param sortBy - Column the table is being sorted by.
+ * @returns Direction that reads most naturally for that column.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export function resolvePlannedMessageManagerDefaultSortOrder(
+    sortBy: PlannedMessageManagerSortField,
+): AdminTableSortOrder {
+    return sortBy === 'lastRun' || sortBy === 'runs' ? 'desc' : 'asc';
+}
+
+/**
+ * Resolves how often one planned message repeats, as a comparable period in milliseconds.
+ *
+ * @param plannedMessage - Planned message being sorted.
+ * @returns Repeat period, or a sentinel standing for cron-driven and one-off messages.
+ *
+ * @private function of `resolvePlannedMessageSortValue`
+ */
+function resolvePlannedMessageFrequencySortValue(plannedMessage: PlannedMessageManagerRecord): number {
+    if (plannedMessage.recurrenceKind === 'INTERVAL') {
+        return plannedMessage.recurrenceIntervalMs || 0;
+    }
+
+    return plannedMessage.recurrenceKind === 'CRON'
+        ? CRON_PLANNED_MESSAGE_FREQUENCY_SORT_VALUE
+        : SINGLE_RUN_PLANNED_MESSAGE_FREQUENCY_SORT_VALUE;
+}

package/apps/agents-server/src/app/admin/planned-messages/usePlannedMessageManagerData.ts

@@ -0,0 +1,116 @@
+'use client';
+
+import { $fetchAdminPlannedMessages, type PlannedMessageManagerRecord } from '@/src/utils/plannedMessagesAdmin';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Default auto-refresh cadence of the planned-message manager.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+const DEFAULT_PLANNED_MESSAGE_POLL_INTERVAL_MS = 10_000;
+
+/**
+ * Live planned-message listing shared by every part of the manager.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export type PlannedMessageManagerData = {
+    readonly plannedMessages: Array<PlannedMessageManagerRecord>;
+    readonly generatedAt: string | null;
+    readonly hasMore: boolean;
+    readonly isLoading: boolean;
+    readonly isRefreshing: boolean;
+    readonly error: string | null;
+    readonly pollIntervalMs: number;
+    readonly refreshNow: () => void;
+    readonly updatePollIntervalMs: (value: string) => void;
+};
+
+/**
+ * Loads every planned message of the server and keeps the listing fresh.
+ *
+ * @returns Live planned-message listing with its refresh controls.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export function usePlannedMessageManagerData(): PlannedMessageManagerData {
+    const [plannedMessages, setPlannedMessages] = useState<Array<PlannedMessageManagerRecord>>([]);
+    const [generatedAt, setGeneratedAt] = useState<string | null>(null);
+    const [hasMore, setHasMore] = useState(false);
+    const [isLoading, setIsLoading] = useState(true);
+    const [isRefreshing, setIsRefreshing] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const [pollIntervalMs, setPollIntervalMs] = useState(DEFAULT_PLANNED_MESSAGE_POLL_INTERVAL_MS);
+    const [refreshNonce, setRefreshNonce] = useState(0);
+    const hasLoadedOnceRef = useRef(false);
+
+    const refreshNow = useCallback((): void => {
+        setRefreshNonce((currentNonce) => currentNonce + 1);
+    }, []);
+
+    const updatePollIntervalMs = useCallback((value: string): void => {
+        const parsedPollIntervalMs = Number.parseInt(value, 10);
+        setPollIntervalMs(Number.isFinite(parsedPollIntervalMs) ? parsedPollIntervalMs : 0);
+    }, []);
+
+    useEffect(() => {
+        let isCancelled = false;
+
+        async function loadPlannedMessages(): Promise<void> {
+            if (hasLoadedOnceRef.current) {
+                setIsRefreshing(true);
+            }
+
+            try {
+                const response = await $fetchAdminPlannedMessages();
+
+                if (isCancelled) {
+                    return;
+                }
+
+                setPlannedMessages(response.items);
+                setGeneratedAt(response.generatedAt);
+                setHasMore(response.hasMore);
+                setError(null);
+            } catch (loadError) {
+                if (!isCancelled) {
+                    setError(loadError instanceof Error ? loadError.message : 'Failed to load planned messages.');
+                }
+            } finally {
+                if (!isCancelled) {
+                    setIsLoading(false);
+                    setIsRefreshing(false);
+                    hasLoadedOnceRef.current = true;
+                }
+            }
+        }
+
+        void loadPlannedMessages();
+
+        return () => {
+            isCancelled = true;
+        };
+    }, [refreshNonce]);
+
+    useEffect(() => {
+        if (pollIntervalMs <= 0) {
+            return;
+        }
+
+        const refreshTimer = window.setInterval(() => refreshNow(), pollIntervalMs);
+        return () => window.clearInterval(refreshTimer);
+    }, [pollIntervalMs, refreshNow]);
+
+    return {
+        plannedMessages,
+        generatedAt,
+        hasMore,
+        isLoading,
+        isRefreshing,
+        error,
+        pollIntervalMs,
+        refreshNow,
+        updatePollIntervalMs,
+    };
+}