@promptbook/cli 0.114.0-2 → 0.114.0-20

package/apps/agents-server/src/utils/userChatClient.ts

@@ -12,12 +12,10 @@ export { fetchAgentUserTimeouts } from './userChatClient/fetchAgentUserTimeouts'
 export { fetchUserChat } from './userChatClient/fetchUserChat';
 export { fetchUserChats } from './userChatClient/fetchUserChats';
 export { removeUserChat } from './userChatClient/removeUserChat';
-export { runAgentUserTimeoutBulkAction } from './userChatClient/runAgentUserTimeoutBulkAction';
 export { saveUserChatDraft } from './userChatClient/saveUserChatDraft';
 export { saveUserChatMessages } from './userChatClient/saveUserChatMessages';
 export { sendUserChatMessage } from './userChatClient/sendUserChatMessage';
 export { streamUserChat } from './userChatClient/streamUserChat';
-export { updateAgentUserTimeout } from './userChatClient/updateAgentUserTimeout';
 export { UserChatApiError } from './userChatClient/UserChatApiError';
 
 /**
@@ -39,12 +37,21 @@ export type UserChatSummary = {
     updatedAt: string;
     lastMessageAt: string | null;
     source: UserChatSource;
+    /**
+     * Database user id owning the chat, used to link a super-admin to its owner.
+     */
+    userId?: number;
     isReadOnly: boolean;
     /**
      * True when the chat belongs to a different user than the current viewer
      * (visible only to admins/super-admins browsing external chats).
      */
     isExternalUserChat?: boolean;
+    /**
+     * True for the singleton goal chat the agent keeps with itself, which is pinned above
+     * every other chat and rendered with its own icon.
+     */
+    isAgentGoalChat?: boolean;
     messagesCount: number;
     title: string;
     preview: string;
@@ -100,6 +107,10 @@ export type UserChatTimeout = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -134,35 +145,6 @@ export type AgentUserTimeoutListResponse = {
     generatedAt: string;
 };
 
-/**
- * Editable timeout fields accepted by the agent-wide timeout update endpoint.
- */
-export type AgentUserTimeoutUpdatePayload = {
-    dueAt?: string;
-    recurrenceIntervalMs?: number | null;
-    message?: string | null;
-    parameters?: Record<string, unknown>;
-    paused?: boolean;
-    extendByMs?: number;
-};
-
-/**
- * Supported bulk timeout actions in the agent-wide timeout manager.
- */
-export type AgentUserTimeoutBulkAction = 'cancel_all_active' | 'pause_all_active' | 'resume_all_paused';
-
-/**
- * API payload returned after one bulk timeout action.
- */
-export type AgentUserTimeoutBulkActionResponse = {
-    action: AgentUserTimeoutBulkAction;
-    matchedCount: number;
-    updatedCount: number;
-    timeoutIds: Array<string>;
-    hasMore: boolean;
-    generatedAt: string;
-};
-
 /**
  * API payload for list endpoint.
  */

package/apps/agents-server/src/utils/userChatTimeout/UserChatTimeoutRecord.ts

@@ -27,6 +27,10 @@ export type UserChatTimeoutRecord = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -55,6 +59,10 @@ export type UserChatTimeoutRow = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -83,6 +91,10 @@ export type UserChatTimeoutInsert = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     queuedAt: string;
     startedAt?: string | null;
     completedAt?: string | null;
@@ -97,15 +109,22 @@ export type UserChatTimeoutInsert = {
 
 /**
  * Input used when persisting one new chat timeout.
+ *
+ * The schedule fields describe the whole life of a planned message, so `durationMs` and `dueAt` are
+ * only needed by a caller that schedules one plain wake-up at a fixed delay.
  */
 export type CreateUserChatTimeoutOptions = {
     id?: string;
     userId: number;
     agentPermanentId: string;
     chatId: string;
-    durationMs: number;
+    durationMs?: number;
     dueAt?: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     message?: string;
     parameters?: UserChatTimeoutParameters;
 };
@@ -130,11 +149,25 @@ export type ListUserChatTimeoutsOptions = {
     onlyActive?: boolean;
 };
 
+/**
+ * Query options for listing the timeouts of every agent on the server.
+ */
+export type ListAllUserChatTimeoutsOptions = {
+    /**
+     * Largest number of rows to return, newest first.
+     */
+    limit: number;
+};
+
 /**
  * Query options for loading one timeout scoped only to user + agent.
  */
 export type GetAgentScopedUserChatTimeoutOptions = {
-    userId: number;
+    /**
+     * Owning user, or `undefined` to span every user of the agent
+     * (used by the agent goal chat, which plans on behalf of the agent itself).
+     */
+    userId?: number;
     agentPermanentId: string;
     timeoutId: string;
 };
@@ -143,7 +176,11 @@ export type GetAgentScopedUserChatTimeoutOptions = {
  * Query options for listing all timeouts owned by one user+agent across chats.
  */
 export type ListAgentUserChatTimeoutsOptions = {
-    userId: number;
+    /**
+     * Owning user, or `undefined` to span every user of the agent
+     * (used by the agent goal chat, which plans on behalf of the agent itself).
+     */
+    userId?: number;
     agentPermanentId: string;
     statuses?: ReadonlyArray<UserChatTimeoutStatus>;
     includePaused?: boolean;
@@ -154,10 +191,17 @@ export type ListAgentUserChatTimeoutsOptions = {
 
 /**
  * Mutable fields accepted when editing one agent-scoped timeout.
+ *
+ * Every schedule field that is present is written, so leaving one out keeps it as it is and passing
+ * `null` removes it.
  */
 export type UpdateAgentScopedUserChatTimeoutPatch = {
     dueAt?: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     message?: string | null;
     parameters?: UserChatTimeoutParameters;
     pausedAt?: string | null;

package/apps/agents-server/src/utils/userChatTimeout/agentScopedTimeoutBulkActions.ts

@@ -1,6 +1,7 @@
+import { setAgentScopedUserChatTimeoutPausedState } from './setAgentScopedUserChatTimeoutPausedState';
 import type { UserChatTimeoutStatus, UserChatTimeoutRecord } from './UserChatTimeoutRecord';
-import { listAgentUserChatTimeouts, updateAgentScopedUserChatTimeout } from './userChatTimeoutStore';
-import { cancelScheduledUserChatTimeout, notifyUserChatTimeoutScheduleChanged } from './userChatTimeoutWorker';
+import { listAgentUserChatTimeouts } from './userChatTimeoutStore';
+import { cancelScheduledUserChatTimeout } from './userChatTimeoutWorker';
 
 /**
  * Number of timeout rows loaded per page while collecting bulk-mutation targets.
@@ -68,22 +69,18 @@ export async function pauseAllActiveAgentScopedUserChatTimeouts(options: {
         statuses: ['QUEUED'],
         paused: false,
     });
-    const pausedAtIso = new Date().toISOString();
     const pausedTimeoutIds: Array<string> = [];
 
     for (const timeout of collectedTimeouts.timeouts) {
-        const updatedTimeout = await updateAgentScopedUserChatTimeout({
+        const pauseResult = await setAgentScopedUserChatTimeoutPausedState({
             userId: options.userId,
             agentPermanentId: options.agentPermanentId,
             timeoutId: timeout.timeoutId,
-            patch: {
-                pausedAt: pausedAtIso,
-            },
+            isPaused: true,
         });
 
-        if (updatedTimeout && updatedTimeout.pausedAt) {
-            notifyUserChatTimeoutScheduleChanged(updatedTimeout);
-            pausedTimeoutIds.push(updatedTimeout.timeoutId);
+        if (pauseResult.isApplied) {
+            pausedTimeoutIds.push(pauseResult.plannedMessage.timeoutId);
         }
     }
 
@@ -111,18 +108,15 @@ export async function resumeAllPausedAgentScopedUserChatTimeouts(options: {
     const resumedTimeoutIds: Array<string> = [];
 
     for (const timeout of collectedTimeouts.timeouts) {
-        const updatedTimeout = await updateAgentScopedUserChatTimeout({
+        const resumeResult = await setAgentScopedUserChatTimeoutPausedState({
             userId: options.userId,
             agentPermanentId: options.agentPermanentId,
             timeoutId: timeout.timeoutId,
-            patch: {
-                pausedAt: null,
-            },
+            isPaused: false,
         });
 
-        if (updatedTimeout && !updatedTimeout.pausedAt) {
-            notifyUserChatTimeoutScheduleChanged(updatedTimeout);
-            resumedTimeoutIds.push(updatedTimeout.timeoutId);
+        if (resumeResult.isApplied) {
+            resumedTimeoutIds.push(resumeResult.plannedMessage.timeoutId);
         }
     }
 

package/apps/agents-server/src/utils/userChatTimeout/createTimeoutWakeUpMessage.ts

@@ -1,22 +1,54 @@
 import { spaceTrim } from 'spacetrim';
+import {
+    describeAgentPlannedMessageSchedule,
+    type AgentPlannedMessageScheduleDescription,
+} from '../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
 
 /**
  * Builds the synthetic user-like message injected when a timeout elapses.
  *
+ * A planned message carries its whole schedule into its own wake-up, so the agent immediately knows
+ * whether this was its last run and does not have to plan anything again just to keep the plan alive.
+ *
  * @private internal utility of userChatTimeout
  */
-export function createTimeoutWakeUpMessage(options: {
-    readonly timeoutId: string;
-    readonly durationMs: number;
-    readonly message?: string | null;
-}): string {
+export function createTimeoutWakeUpMessage(
+    options: AgentPlannedMessageScheduleDescription & {
+        readonly timeoutId: string;
+        readonly durationMs: number;
+        readonly message?: string | null;
+    },
+): string {
     const message = options.message?.trim() || '';
 
     return spaceTrim(
         (block) => `
-            ⏱️ Timeout elapsed after ${options.durationMs}ms.
+            ${createTimeoutWakeUpHeadline(options)}
             timeoutId: ${options.timeoutId}
             ${message ? block(message) : ''}
         `,
     );
 }
+
+/**
+ * Builds the first line of one wake-up, telling the agent what woke it and where in its plan it is.
+ *
+ * @param options - Schedule of the planned message together with the plain timeout duration.
+ * @returns Headline of the wake-up message.
+ *
+ * @private internal utility of `createTimeoutWakeUpMessage`
+ */
+function createTimeoutWakeUpHeadline(
+    options: AgentPlannedMessageScheduleDescription & { readonly durationMs: number },
+): string {
+    if (options.intervalMs || options.cronExpression) {
+        // Note: The next wake-up is resolved only after this one is queued, so the schedule is described without it
+        return `⏱️ Planned message elapsed, ${describeAgentPlannedMessageSchedule({ ...options, dueAt: null })}.`;
+    }
+
+    if (options.maxRunCount || options.startsAt) {
+        return '⏱️ Planned message elapsed, this was its only wake-up.';
+    }
+
+    return `⏱️ Timeout elapsed after ${options.durationMs}ms.`;
+}

package/apps/agents-server/src/utils/userChatTimeout/plannedMessageSchedule/PlannedMessageSchedule.ts

@@ -0,0 +1,52 @@
+/**
+ * Shortest repeat interval one planned message may use.
+ *
+ * A planned message wakes a whole agent invocation, so an interval below one minute would turn a plan
+ * into an unattended self-invocation loop. Cron expressions have the very same one-minute resolution.
+ *
+ * @private constant of `plannedMessageSchedule`
+ */
+export const MINIMUM_PLANNED_MESSAGE_INTERVAL_MS = 60_000;
+
+/**
+ * Complete recurrence rule of one planned message.
+ *
+ * A planned message can be a one-shot wake-up, an endless repetition, or anything between the two:
+ * `cronExpression` or `recurrenceIntervalMs` says how it repeats, while `startsAt`, `endsAt`, and
+ * `maxRunCount` bound how long it keeps repeating.
+ *
+ * Field names match `UserChatTimeoutRecord`, so one stored timeout row is already a valid schedule.
+ *
+ * @private type of `plannedMessageSchedule`
+ */
+export type PlannedMessageSchedule = {
+    /**
+     * Five-field cron expression evaluated in the local server time, or `null` when the planned
+     * message does not follow a cron.
+     */
+    readonly cronExpression: string | null;
+
+    /**
+     * Fixed repeat interval in milliseconds, or `null` when the planned message does not repeat at a
+     * fixed interval.
+     */
+    readonly recurrenceIntervalMs: number | null;
+
+    /**
+     * Moment before which the planned message never wakes the agent, or `null` when it may start
+     * immediately.
+     */
+    readonly startsAt: string | null;
+
+    /**
+     * Moment after which the planned message never wakes the agent again, or `null` when it has no
+     * ending date.
+     */
+    readonly endsAt: string | null;
+
+    /**
+     * Total number of times the planned message wakes the agent, or `null` when it repeats until it
+     * is cancelled.
+     */
+    readonly maxRunCount: number | null;
+};

package/apps/agents-server/src/utils/userChatTimeout/plannedMessageSchedule/hasPlannedMessageRecurrence.ts

@@ -0,0 +1,13 @@
+import type { PlannedMessageSchedule } from './PlannedMessageSchedule';
+
+/**
+ * Determines whether one planned message can wake the agent more than once.
+ *
+ * @param schedule - Recurrence rule of the planned message.
+ * @returns `true` when the schedule has a cron expression or a fixed repeat interval.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function hasPlannedMessageRecurrence(schedule: PlannedMessageSchedule): boolean {
+    return Boolean(schedule.cronExpression || schedule.recurrenceIntervalMs);
+}

package/apps/agents-server/src/utils/userChatTimeout/plannedMessageSchedule/isPlannedMessageScheduleFinished.ts

@@ -0,0 +1,30 @@
+import type { PlannedMessageSchedule } from './PlannedMessageSchedule';
+import { normalizePlannedMessageDateIso } from './normalizePlannedMessageScheduleValues';
+
+/**
+ * Determines whether one planned message must never wake the agent again.
+ *
+ * A planned message is finished once it ran as many times as it was planned to run, or once its
+ * ending date has passed. Such a message is closed instead of being fired, so an agent is never woken
+ * by a plan it already completed.
+ *
+ * @param options - Recurrence rule, how many times it already ran, and the moment being judged.
+ * @returns `true` when no further wake-up is allowed.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function isPlannedMessageScheduleFinished(options: {
+    readonly schedule: PlannedMessageSchedule;
+    readonly completedRunCount: number;
+    readonly atDate: Date;
+}): boolean {
+    const { schedule, completedRunCount, atDate } = options;
+
+    if (schedule.maxRunCount !== null && completedRunCount >= schedule.maxRunCount) {
+        return true;
+    }
+
+    const endsAtIso = normalizePlannedMessageDateIso(schedule.endsAt);
+
+    return endsAtIso !== null && atDate.getTime() > Date.parse(endsAtIso);
+}

package/apps/agents-server/src/utils/userChatTimeout/plannedMessageSchedule/normalizePlannedMessageScheduleValues.ts

@@ -0,0 +1,62 @@
+/**
+ * Normalizes one stored or untrusted total run count.
+ *
+ * @param value - Raw run-count limit.
+ * @returns Whole positive limit, or `null` when the planned message repeats without a count limit.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function normalizePlannedMessageMaxRunCount(value: unknown): number | null {
+    const maxRunCount = Number(value);
+
+    if (!Number.isFinite(maxRunCount) || maxRunCount < 1) {
+        return null;
+    }
+
+    return Math.floor(maxRunCount);
+}
+
+/**
+ * Normalizes one stored or untrusted schedule boundary into an ISO timestamp.
+ *
+ * @param value - Raw date value.
+ * @returns ISO timestamp, or `null` when the value is not a usable date.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function normalizePlannedMessageDateIso(value: unknown): string | null {
+    if (value === null || value === undefined || value === '') {
+        return null;
+    }
+
+    if (typeof value !== 'string' && typeof value !== 'number' && !(value instanceof Date)) {
+        return null;
+    }
+
+    const date = value instanceof Date ? value : new Date(value);
+
+    if (Number.isNaN(date.getTime())) {
+        return null;
+    }
+
+    return date.toISOString();
+}
+
+/**
+ * Normalizes one stored or untrusted cron expression without validating its fields.
+ *
+ * Stored expressions were already validated when they were planned, and mapping one database row must
+ * never throw, so the field syntax is checked only where a new schedule is accepted.
+ *
+ * @param value - Raw cron expression.
+ * @returns Trimmed expression, or `null` when there is none.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function normalizePlannedMessageCronExpression(value: unknown): string | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    return value.trim() || null;
+}

package/apps/agents-server/src/utils/userChatTimeout/plannedMessageSchedule/parsePlannedMessageSchedule.ts

@@ -0,0 +1,202 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../../src/errors/ParseError';
+import { normalizeCronExpression } from '../../cronExpression';
+import { MINIMUM_PLANNED_MESSAGE_INTERVAL_MS, type PlannedMessageSchedule } from './PlannedMessageSchedule';
+import { normalizePlannedMessageDateIso } from './normalizePlannedMessageScheduleValues';
+
+/**
+ * Untrusted schedule fields of one planned message, as written by a model, a coding harness, or the
+ * internal runtime API.
+ *
+ * A missing field means "not requested", while an explicit `null` means "no such bound", which is what
+ * lets one update remove an ending date or a run-count limit.
+ *
+ * @private type of `plannedMessageSchedule`
+ */
+export type PlannedMessageScheduleInput = {
+    readonly milliseconds?: unknown;
+    readonly cronExpression?: unknown;
+    readonly startsAt?: unknown;
+    readonly endsAt?: unknown;
+    readonly maxRunCount?: unknown;
+};
+
+/**
+ * Parses one untrusted planned-message schedule.
+ *
+ * @param input - Schedule fields requested by an agent.
+ * @returns Validated recurrence rule.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function parsePlannedMessageSchedule(input: PlannedMessageScheduleInput): PlannedMessageSchedule {
+    const cronExpression = parsePlannedMessageCronExpression(input.cronExpression);
+    const recurrenceIntervalMs = parsePlannedMessageIntervalMs(input.milliseconds);
+
+    if (cronExpression !== null && recurrenceIntervalMs !== null) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message schedule.
+
+                - Use either \`cronExpression\` or \`milliseconds\`, **not both**.
+            `),
+        );
+    }
+
+    const startsAt = parsePlannedMessageBoundaryDate(input.startsAt, 'startsAt');
+    const endsAt = parsePlannedMessageBoundaryDate(input.endsAt, 'endsAt');
+
+    if (startsAt !== null && endsAt !== null && Date.parse(endsAt) <= Date.parse(startsAt)) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message schedule.
+
+                - \`endsAt\` must be **after** \`startsAt\`.
+            `),
+        );
+    }
+
+    if (cronExpression === null && recurrenceIntervalMs === null && startsAt === null) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message schedule.
+
+                - Say when the planned message wakes you with \`cronExpression\`, \`milliseconds\`, or \`startsAt\`.
+                - Use \`maxRunCount\` and \`endsAt\` only to **bound** a schedule, never as the schedule itself.
+            `),
+        );
+    }
+
+    return {
+        cronExpression,
+        recurrenceIntervalMs,
+        startsAt,
+        endsAt,
+        maxRunCount: parsePlannedMessageMaxRunCount(input.maxRunCount),
+    };
+}
+
+/**
+ * Parses one untrusted cron expression of a planned message.
+ *
+ * @param rawCronExpression - Untrusted cron expression.
+ * @returns Normalized expression, or `null` when none was requested.
+ *
+ * @private function of `parsePlannedMessageSchedule`
+ */
+function parsePlannedMessageCronExpression(rawCronExpression: unknown): string | null {
+    if (rawCronExpression === undefined || rawCronExpression === null || rawCronExpression === '') {
+        return null;
+    }
+
+    if (typeof rawCronExpression !== 'string') {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message \`cronExpression\`.
+
+                - Use a five-field cron string such as \`0 9 * * 1-5\`.
+            `),
+        );
+    }
+
+    try {
+        return normalizeCronExpression(rawCronExpression);
+    } catch (error) {
+        throw new ParseError(
+            spaceTrim(
+                (block) => `
+                    Invalid planned-message \`cronExpression\`.
+
+                    ${block(error instanceof Error ? error.message : String(error))}
+                `,
+            ),
+        );
+    }
+}
+
+/**
+ * Parses one untrusted repeat interval of a planned message.
+ *
+ * @param rawMilliseconds - Untrusted interval in milliseconds.
+ * @returns Repeat interval in whole milliseconds, or `null` when none was requested.
+ *
+ * @private function of `parsePlannedMessageSchedule`
+ */
+function parsePlannedMessageIntervalMs(rawMilliseconds: unknown): number | null {
+    if (rawMilliseconds === undefined || rawMilliseconds === null) {
+        return null;
+    }
+
+    const milliseconds = Number(rawMilliseconds);
+
+    if (!Number.isFinite(milliseconds) || milliseconds < MINIMUM_PLANNED_MESSAGE_INTERVAL_MS) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message interval.
+
+                - A planned message **repeats** at this interval until it is cancelled or bounded by \`maxRunCount\` or \`endsAt\`.
+                - \`milliseconds\` must be a number of at least \`${MINIMUM_PLANNED_MESSAGE_INTERVAL_MS}\`.
+            `),
+        );
+    }
+
+    return Math.floor(milliseconds);
+}
+
+/**
+ * Parses one untrusted total run count of a planned message.
+ *
+ * @param rawMaxRunCount - Untrusted run-count limit.
+ * @returns Whole positive limit, or `null` when the planned message repeats without a count limit.
+ *
+ * @private function of `parsePlannedMessageSchedule`
+ */
+function parsePlannedMessageMaxRunCount(rawMaxRunCount: unknown): number | null {
+    if (rawMaxRunCount === undefined || rawMaxRunCount === null) {
+        return null;
+    }
+
+    const maxRunCount = Number(rawMaxRunCount);
+
+    if (!Number.isInteger(maxRunCount) || maxRunCount < 1) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message \`maxRunCount\`.
+
+                - Use a whole number of at least \`1\`, which is **how many times in total** the planned message wakes you.
+                - Leave it out for a planned message that repeats until it is cancelled.
+            `),
+        );
+    }
+
+    return maxRunCount;
+}
+
+/**
+ * Parses one untrusted starting or ending date of a planned message.
+ *
+ * @param rawDate - Untrusted date value.
+ * @param fieldName - Field name used in a detailed parse error.
+ * @returns ISO timestamp, or `null` when the boundary was not requested.
+ *
+ * @private function of `parsePlannedMessageSchedule`
+ */
+function parsePlannedMessageBoundaryDate(rawDate: unknown, fieldName: 'startsAt' | 'endsAt'): string | null {
+    if (rawDate === undefined || rawDate === null || rawDate === '') {
+        return null;
+    }
+
+    const dateIso = normalizePlannedMessageDateIso(rawDate);
+
+    if (dateIso === null) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message \`${fieldName}\`.
+
+                - Use an ISO date such as \`2026-08-20T09:00:00.000Z\`.
+            `),
+        );
+    }
+
+    return dateIso;
+}