@promptbook/cli 0.114.0-2 → 0.114.0-21

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

@@ -0,0 +1,189 @@
+'use client';
+
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import { buildAgentProfileHref, buildExistingAgentChatHref } from '@/src/utils/agentRouting/agentRouteHrefs';
+import { isPlannedMessageStillPlanned } from '@/src/utils/plannedMessageManager/isPlannedMessageStillPlanned';
+import type { PlannedMessageManagerRecord } from '@/src/utils/plannedMessagesAdmin';
+import { ArrowUpRight, MessageSquareText } from 'lucide-react';
+import Link from 'next/link';
+import type { PlannedMessageActionKind } from './usePlannedMessageManagerState';
+import {
+    describePlannedMessagePlan,
+    formatPlannedMessageDateTime,
+    formatPlannedMessageEndReason,
+    formatPlannedMessageFrequency,
+    formatPlannedMessageRunCount,
+    PlannedMessageGoalChatBadge,
+    PlannedMessageLifecycleBadge,
+    resolvePlannedMessageText,
+} from './plannedMessageManagerPresentation';
+
+/**
+ * Props for one planned-message table row.
+ *
+ * @private function of PlannedMessageManagerTableCard
+ */
+type PlannedMessageManagerRowProps = {
+    readonly plannedMessage: PlannedMessageManagerRecord;
+    readonly language: ServerLanguageCode;
+    readonly busyTimeoutId: string | null;
+    readonly busyAction: PlannedMessageActionKind | null;
+    readonly onEdit: (plannedMessage: PlannedMessageManagerRecord) => void;
+    readonly onTogglePaused: (plannedMessage: PlannedMessageManagerRecord) => Promise<void>;
+    readonly onCancel: (plannedMessage: PlannedMessageManagerRecord) => Promise<void>;
+};
+
+/**
+ * Shared classes of the small row action buttons.
+ *
+ * @private function of PlannedMessageManagerRow
+ */
+const PLANNED_MESSAGE_ACTION_BUTTON_CLASS_NAME =
+    'rounded-md border px-2.5 py-1 text-[11px] font-semibold disabled:cursor-not-allowed disabled:opacity-50';
+
+/**
+ * Renders one planned message with its plan, its state, and what can be done to it.
+ *
+ * @private function of PlannedMessageManagerTableCard
+ */
+export function PlannedMessageManagerRow({
+    plannedMessage,
+    language,
+    busyTimeoutId,
+    busyAction,
+    onEdit,
+    onTogglePaused,
+    onCancel,
+}: PlannedMessageManagerRowProps) {
+    const isStillPlanned = isPlannedMessageStillPlanned(plannedMessage.lifecycle);
+    const isFiringNow = plannedMessage.lifecycle === 'ONGOING';
+    const isBusy = busyTimeoutId === plannedMessage.timeoutId;
+    const isPaused = plannedMessage.pausedAt !== null;
+    const endReasonLabel = formatPlannedMessageEndReason(plannedMessage.endReason);
+
+    /**
+     * Says whether one action of this very row is running right now.
+     */
+    function isRunningAction(action: PlannedMessageActionKind): boolean {
+        return isBusy && busyAction === action;
+    }
+
+    return (
+        <tr className="align-top">
+            <td className="px-4 py-3">
+                <div className="max-w-md text-[12px] font-medium text-gray-900">
+                    {resolvePlannedMessageText(plannedMessage)}
+                </div>
+                <div className="mt-1 flex flex-wrap items-center gap-2">
+                    <span className="break-all font-mono text-[11px] text-gray-500">{plannedMessage.timeoutId}</span>
+                    <PlannedMessageGoalChatBadge plannedMessage={plannedMessage} />
+                </div>
+            </td>
+
+            <td className="px-4 py-3">
+                <div className="text-[12px] font-medium text-gray-900">
+                    {plannedMessage.agentName || plannedMessage.agentPermanentId}
+                </div>
+                <div className="break-all text-[11px] text-gray-500">{plannedMessage.agentPermanentId}</div>
+                <div className="mt-1 text-[11px] text-gray-500">
+                    {plannedMessage.username || `#${plannedMessage.userId}`}
+                </div>
+                <div className="mt-2 flex flex-wrap gap-2">
+                    <Link
+                        href={buildAgentProfileHref(plannedMessage.agentPermanentId)}
+                        className="inline-flex items-center gap-1 rounded-md border border-blue-200 bg-blue-50 px-2.5 py-1 text-[11px] font-semibold text-blue-700 hover:bg-blue-100"
+                        title="Open the agent this planned message belongs to"
+                    >
+                        <ArrowUpRight className="h-3.5 w-3.5" />
+                        Open agent
+                    </Link>
+                    <Link
+                        href={buildExistingAgentChatHref(plannedMessage.agentPermanentId, plannedMessage.chatId)}
+                        className="inline-flex items-center gap-1 rounded-md border border-gray-200 bg-white px-2.5 py-1 text-[11px] font-semibold text-gray-700 hover:bg-gray-50"
+                        title="Open the chat this planned message wakes up"
+                    >
+                        <MessageSquareText className="h-3.5 w-3.5" />
+                        Open chat
+                    </Link>
+                </div>
+            </td>
+
+            <td className="px-4 py-3">
+                <div className="text-[12px] text-gray-900">{formatPlannedMessageFrequency(plannedMessage)}</div>
+                <div className="mt-1 max-w-xs text-[11px] text-gray-500">
+                    {describePlannedMessagePlan(plannedMessage)}
+                </div>
+            </td>
+
+            <td className="px-4 py-3 text-[11px] text-gray-800">
+                {isStillPlanned ? formatPlannedMessageDateTime(plannedMessage.dueAt, language) : '-'}
+                {plannedMessage.startsAt !== null && (
+                    <div className="text-[11px] text-gray-500">
+                        from {formatPlannedMessageDateTime(plannedMessage.startsAt, language)}
+                    </div>
+                )}
+                {plannedMessage.endsAt !== null && (
+                    <div className="text-[11px] text-gray-500">
+                        until {formatPlannedMessageDateTime(plannedMessage.endsAt, language)}
+                    </div>
+                )}
+            </td>
+
+            <td className="px-4 py-3 text-[11px] text-gray-800">
+                {formatPlannedMessageDateTime(plannedMessage.lastFiredAt, language)}
+            </td>
+
+            <td className="px-4 py-3 text-[11px] text-gray-800">{formatPlannedMessageRunCount(plannedMessage)}</td>
+
+            <td className="px-4 py-3">
+                <PlannedMessageLifecycleBadge lifecycle={plannedMessage.lifecycle} />
+                {endReasonLabel !== null && <div className="mt-1 text-[11px] text-gray-500">{endReasonLabel}</div>}
+                {plannedMessage.failureReason !== null && (
+                    <div className="mt-1 max-w-xs break-words text-[11px] text-rose-700">
+                        {plannedMessage.failureReason}
+                    </div>
+                )}
+            </td>
+
+            <td className="px-4 py-3">
+                <div className="flex flex-wrap justify-end gap-2">
+                    <button
+                        type="button"
+                        onClick={() => onEdit(plannedMessage)}
+                        disabled={!isStillPlanned || isFiringNow || isBusy}
+                        className={`${PLANNED_MESSAGE_ACTION_BUTTON_CLASS_NAME} border-gray-300 bg-white text-gray-700 hover:bg-gray-50`}
+                        title={
+                            isFiringNow
+                                ? 'This planned message is waking its agent right now, so its plan cannot be changed'
+                                : 'Change the plan or the text of this planned message'
+                        }
+                    >
+                        Edit
+                    </button>
+                    <button
+                        type="button"
+                        onClick={() => void onTogglePaused(plannedMessage)}
+                        disabled={!isStillPlanned || isFiringNow || isBusy}
+                        className={`${PLANNED_MESSAGE_ACTION_BUTTON_CLASS_NAME} border-orange-200 bg-orange-50 text-orange-700 hover:bg-orange-100`}
+                        title={
+                            isPaused
+                                ? 'Let this planned message wake its agent again'
+                                : 'Hold this planned message back without cancelling it'
+                        }
+                    >
+                        {isRunningAction('pause') ? 'Working…' : isPaused ? 'Resume' : 'Pause'}
+                    </button>
+                    <button
+                        type="button"
+                        onClick={() => void onCancel(plannedMessage)}
+                        disabled={!isStillPlanned || isBusy}
+                        className={`${PLANNED_MESSAGE_ACTION_BUTTON_CLASS_NAME} border-red-200 bg-red-50 text-red-700 hover:bg-red-100`}
+                        title="Cancel this planned message so it never wakes its agent again"
+                    >
+                        {isRunningAction('cancel') ? 'Cancelling…' : 'Cancel'}
+                    </button>
+                </div>
+            </td>
+        </tr>
+    );
+}

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

@@ -0,0 +1,60 @@
+'use client';
+
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import type { PlannedMessageManagerCounters } from '@/src/utils/plannedMessageManager/createPlannedMessageManagerCounters';
+import { AdminMetricCard } from '../_components/AdminMetricCard';
+import { formatPlannedMessageDateTime } from './plannedMessageManagerPresentation';
+
+/**
+ * Props for the planned-message summary metrics grid.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+type PlannedMessageManagerSummaryMetricsProps = {
+    readonly counters: PlannedMessageManagerCounters;
+    readonly isLoading: boolean;
+    readonly language: ServerLanguageCode;
+};
+
+/**
+ * Renders the summary counters above the planned-message table.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export function PlannedMessageManagerSummaryMetrics({
+    counters,
+    isLoading,
+    language,
+}: PlannedMessageManagerSummaryMetricsProps) {
+    /**
+     * Formats one counter, keeping the loading placeholder until the first listing arrives.
+     */
+    function formatCounter(count: number): string {
+        return isLoading ? '...' : count.toLocaleString();
+    }
+
+    return (
+        <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
+            <AdminMetricCard
+                label="Ongoing"
+                value={formatCounter(counters.countByLifecycle.ONGOING)}
+                caption="Waking their agent right now"
+            />
+            <AdminMetricCard
+                label="Scheduled"
+                value={formatCounter(counters.countByLifecycle.SCHEDULED + counters.countByLifecycle.NOT_STARTED)}
+                caption="Wake-ups still ahead"
+            />
+            <AdminMetricCard
+                label="Paused"
+                value={formatCounter(counters.countByLifecycle.PAUSED)}
+                caption="Held back until resumed"
+            />
+            <AdminMetricCard
+                label="Next wake-up"
+                value={isLoading ? '...' : formatPlannedMessageDateTime(counters.nextDueAt, language)}
+                caption="Earliest planned wake-up"
+            />
+        </div>
+    );
+}

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

@@ -0,0 +1,147 @@
+'use client';
+
+import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
+import type { PlannedMessageManagerSortField } from '@/src/utils/plannedMessagesAdmin';
+import { Card } from '../../../components/Homepage/Card';
+import { AdminSortableTableHeaderCell } from '../_components/AdminSortableTableHeaderCell';
+import { PlannedMessageManagerRow } from './PlannedMessageManagerRow';
+import type { UsePlannedMessageManagerStateResult } from './usePlannedMessageManagerState';
+
+/**
+ * Sortable columns of the planned-message table, with the label used in their sort tooltip.
+ *
+ * @private function of PlannedMessageManagerTableCard
+ */
+const PLANNED_MESSAGE_SORT_COLUMNS: ReadonlyArray<{
+    readonly sortBy: PlannedMessageManagerSortField;
+    readonly heading: string;
+    readonly label: string;
+}> = [
+    { sortBy: 'plannedMessage', heading: 'Planned message', label: 'planned message' },
+    { sortBy: 'agent', heading: 'Agent', label: 'agent' },
+    { sortBy: 'frequency', heading: 'Frequency', label: 'frequency' },
+    { sortBy: 'nextRun', heading: 'Next run', label: 'next run' },
+    { sortBy: 'lastRun', heading: 'Last run', label: 'last run' },
+    { sortBy: 'runs', heading: 'Runs', label: 'runs' },
+    { sortBy: 'state', heading: 'State', label: 'state' },
+];
+
+/**
+ * Props for the planned-message table card.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+type PlannedMessageManagerTableCardProps = {
+    readonly language: ServerLanguageCode;
+    readonly state: UsePlannedMessageManagerStateResult;
+};
+
+/**
+ * Renders the planned-message table with its loading, empty, and paging states.
+ *
+ * @private function of PlannedMessageManagerClient
+ */
+export function PlannedMessageManagerTableCard({ language, state }: PlannedMessageManagerTableCardProps) {
+    const firstVisibleIndex = Math.min((state.page - 1) * state.pageSize + 1, state.matchedCount);
+    const lastVisibleIndex = Math.min(state.page * state.pageSize, state.matchedCount);
+
+    return (
+        <Card className="hover:border-gray-200 hover:shadow-md">
+            <div className="flex items-center justify-between gap-4">
+                <div>
+                    <h2 className="text-lg font-medium text-gray-900">
+                        Planned messages ({state.matchedCount.toLocaleString()})
+                    </h2>
+                    <p className="mt-1 text-sm text-gray-500">
+                        Every wake-up an agent planned for itself or for one of its chats.
+                    </p>
+                </div>
+                {state.data.isRefreshing ? (
+                    <span className="text-xs font-medium text-blue-600">Refreshing…</span>
+                ) : null}
+            </div>
+
+            {state.data.isLoading ? (
+                <div className="py-10 text-center text-sm text-gray-500">Loading planned messages…</div>
+            ) : state.visiblePlannedMessages.length === 0 ? (
+                <div className="py-10 text-center text-sm text-gray-500">
+                    No planned message matches the selected filters.
+                </div>
+            ) : (
+                <div className="mt-4 overflow-x-auto">
+                    <table className="min-w-full divide-y divide-gray-200 text-xs">
+                        <thead className="bg-gray-50 text-gray-500">
+                            <tr>
+                                {PLANNED_MESSAGE_SORT_COLUMNS.map((column) => (
+                                    <AdminSortableTableHeaderCell
+                                        key={column.sortBy}
+                                        className="px-4 py-3 text-left font-semibold"
+                                        label={column.label}
+                                        sortBy={column.sortBy}
+                                        activeSortBy={state.sortBy}
+                                        sortOrder={state.sortOrder}
+                                        onSortChange={state.handleSortChange}
+                                    >
+                                        {column.heading}
+                                    </AdminSortableTableHeaderCell>
+                                ))}
+                                <th className="px-4 py-3 text-right font-semibold">Actions</th>
+                            </tr>
+                        </thead>
+                        <tbody className="divide-y divide-gray-200 bg-white">
+                            {state.visiblePlannedMessages.map((plannedMessage) => (
+                                <PlannedMessageManagerRow
+                                    key={plannedMessage.timeoutId}
+                                    plannedMessage={plannedMessage}
+                                    language={language}
+                                    busyTimeoutId={state.busyTimeoutId}
+                                    busyAction={state.busyAction}
+                                    onEdit={state.openPlannedMessageEditor}
+                                    onTogglePaused={state.togglePlannedMessagePaused}
+                                    onCancel={state.cancelPlannedMessage}
+                                />
+                            ))}
+                        </tbody>
+                    </table>
+                </div>
+            )}
+
+            <div className="mt-4 flex flex-col items-center justify-between gap-3 border-t border-gray-100 pt-4 text-xs text-gray-600 md:flex-row">
+                <div>
+                    {state.matchedCount > 0 ? (
+                        <>
+                            Showing <span className="font-semibold">{firstVisibleIndex}</span> –{' '}
+                            <span className="font-semibold">{lastVisibleIndex}</span> of{' '}
+                            <span className="font-semibold">{state.matchedCount}</span> planned messages
+                        </>
+                    ) : (
+                        'No planned messages'
+                    )}
+                </div>
+
+                <div className="flex items-center gap-2">
+                    <button
+                        type="button"
+                        onClick={state.goToPreviousPage}
+                        disabled={state.isPreviousPageDisabled}
+                        className="rounded-md border border-gray-300 px-3 py-1.5 font-medium text-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+                    >
+                        Previous
+                    </button>
+                    <span>
+                        Page <span className="font-semibold">{state.page}</span> of{' '}
+                        <span className="font-semibold">{state.totalPages}</span>
+                    </span>
+                    <button
+                        type="button"
+                        onClick={state.goToNextPage}
+                        disabled={state.isNextPageDisabled}
+                        className="rounded-md border border-gray-300 px-3 py-1.5 font-medium text-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+                    >
+                        Next
+                    </button>
+                </div>
+            </div>
+        </Card>
+    );
+}

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

@@ -0,0 +1,17 @@
+import { ForbiddenPage } from '../../../components/ForbiddenPage/ForbiddenPage';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
+import { isUserGlobalAdmin } from '../../../utils/isUserGlobalAdmin';
+import { PlannedMessageManagerClient } from './PlannedMessageManagerClient';
+
+/**
+ * Admin page managing every planned message (durable chat timeout) of the server.
+ */
+export default async function AdminPlannedMessagesPage() {
+    const [isAdmin, isSuperAdmin] = await Promise.all([isUserAdmin(), isUserGlobalAdmin()]);
+
+    if (!isAdmin) {
+        return <ForbiddenPage />;
+    }
+
+    return <PlannedMessageManagerClient isSuperAdmin={isSuperAdmin} />;
+}

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