@promptbook/cli 0.114.0-3 → 0.114.0-30

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