@promptbook/cli 0.114.0-13 → 0.114.0-18

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

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

@@ -0,0 +1,121 @@
+import { resolveNextCronRun } from '../../cronExpression';
+import type { PlannedMessageSchedule } from './PlannedMessageSchedule';
+import { hasPlannedMessageRecurrence } from './hasPlannedMessageRecurrence';
+import { isPlannedMessageScheduleFinished } from './isPlannedMessageScheduleFinished';
+import { normalizePlannedMessageDateIso } from './normalizePlannedMessageScheduleValues';
+
+/**
+ * Resolves when one planned message wakes the agent next.
+ *
+ * This is the single place deciding the whole life of a planned message: it answers both "when does it
+ * fire for the first time" and "when does it fire again after this firing", and it answers `null` when
+ * the plan is over — because it ran often enough, because its ending date passed, or because it never
+ * repeated in the first place.
+ *
+ * @param options - Recurrence rule, how many times the message already ran, the moment to schedule
+ *                  from, and the delay used by a planned message without any recurrence.
+ * @returns Next wake-up time, or `null` when the planned message is finished.
+ *
+ * @private function of `plannedMessageSchedule`
+ */
+export function resolvePlannedMessageDueAt(options: {
+    readonly schedule: PlannedMessageSchedule;
+    readonly completedRunCount: number;
+    readonly afterDate: Date;
+    readonly fallbackDelayMs?: number | null;
+}): Date | null {
+    const { schedule, completedRunCount, afterDate } = options;
+
+    if (isPlannedMessageScheduleFinished({ schedule, completedRunCount, atDate: afterDate })) {
+        return null;
+    }
+
+    const startsAtDate = resolvePlannedMessageStartDate(schedule);
+    const dueAtDate = resolvePlannedMessageCandidateDueAt({
+        schedule,
+        completedRunCount,
+        afterDate,
+        startsAtDate,
+        fallbackDelayMs: options.fallbackDelayMs ?? null,
+    });
+
+    if (dueAtDate === null) {
+        return null;
+    }
+
+    return isPlannedMessageDueAtAfterEnd(schedule, dueAtDate) ? null : dueAtDate;
+}
+
+/**
+ * Resolves the raw next wake-up time before the ending date is applied.
+ *
+ * @param options - Recurrence rule with the resolved starting date and the scheduling moment.
+ * @returns Candidate wake-up time, or `null` when the recurrence rule offers none.
+ *
+ * @private function of `resolvePlannedMessageDueAt`
+ */
+function resolvePlannedMessageCandidateDueAt(options: {
+    readonly schedule: PlannedMessageSchedule;
+    readonly completedRunCount: number;
+    readonly afterDate: Date;
+    readonly startsAtDate: Date | null;
+    readonly fallbackDelayMs: number | null;
+}): Date | null {
+    const { schedule, completedRunCount, afterDate, startsAtDate, fallbackDelayMs } = options;
+
+    if (!hasPlannedMessageRecurrence(schedule) && completedRunCount > 0) {
+        // Note: A planned message without any recurrence wakes the agent exactly once
+        return null;
+    }
+
+    const isWaitingForStart = startsAtDate !== null && startsAtDate.getTime() > afterDate.getTime();
+
+    if (schedule.cronExpression) {
+        // Note: One millisecond before the starting date keeps a cron run happening exactly at that date
+        return resolveNextCronRun(
+            schedule.cronExpression,
+            isWaitingForStart ? new Date(startsAtDate!.getTime() - 1) : afterDate,
+        );
+    }
+
+    if (isWaitingForStart) {
+        // Note: A planned message never wakes the agent before its starting date, and an interval schedule
+        //       wakes it for the first time exactly then
+        return startsAtDate;
+    }
+
+    if (schedule.recurrenceIntervalMs) {
+        return new Date(afterDate.getTime() + schedule.recurrenceIntervalMs);
+    }
+
+    return fallbackDelayMs === null ? null : new Date(afterDate.getTime() + fallbackDelayMs);
+}
+
+/**
+ * Resolves the starting date of one planned message.
+ *
+ * @param schedule - Recurrence rule of the planned message.
+ * @returns Starting date, or `null` when the planned message may start immediately.
+ *
+ * @private function of `resolvePlannedMessageDueAt`
+ */
+function resolvePlannedMessageStartDate(schedule: PlannedMessageSchedule): Date | null {
+    const startsAtIso = normalizePlannedMessageDateIso(schedule.startsAt);
+
+    return startsAtIso === null ? null : new Date(startsAtIso);
+}
+
+/**
+ * Determines whether one candidate wake-up happens after the ending date.
+ *
+ * @param schedule - Recurrence rule of the planned message.
+ * @param dueAtDate - Candidate wake-up time.
+ * @returns `true` when the candidate is outside the planned window.
+ *
+ * @private function of `resolvePlannedMessageDueAt`
+ */
+function isPlannedMessageDueAtAfterEnd(schedule: PlannedMessageSchedule, dueAtDate: Date): boolean {
+    const endsAtIso = normalizePlannedMessageDateIso(schedule.endsAt);
+
+    return endsAtIso !== null && dueAtDate.getTime() > Date.parse(endsAtIso);
+}

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

@@ -0,0 +1,12 @@
+export { MINIMUM_PLANNED_MESSAGE_INTERVAL_MS } from './plannedMessageSchedule/PlannedMessageSchedule';
+export { hasPlannedMessageRecurrence } from './plannedMessageSchedule/hasPlannedMessageRecurrence';
+export { isPlannedMessageScheduleFinished } from './plannedMessageSchedule/isPlannedMessageScheduleFinished';
+export {
+    normalizePlannedMessageCronExpression,
+    normalizePlannedMessageDateIso,
+    normalizePlannedMessageMaxRunCount,
+} from './plannedMessageSchedule/normalizePlannedMessageScheduleValues';
+export { parsePlannedMessageSchedule } from './plannedMessageSchedule/parsePlannedMessageSchedule';
+export { resolvePlannedMessageDueAt } from './plannedMessageSchedule/resolvePlannedMessageDueAt';
+export type { PlannedMessageSchedule } from './plannedMessageSchedule/PlannedMessageSchedule';
+export type { PlannedMessageScheduleInput } from './plannedMessageSchedule/parsePlannedMessageSchedule';

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

@@ -0,0 +1,66 @@
+import type { UserChatTimeoutRecord } from './UserChatTimeoutRecord';
+import { updateAgentScopedUserChatTimeout } from './userChatTimeoutStore';
+import { notifyUserChatTimeoutScheduleChanged } from './userChatTimeoutWorker';
+
+/**
+ * Outcome of holding one planned message back, or letting it go again.
+ *
+ * `isApplied` is `false` when the planned message could not take the requested state — because it is
+ * firing right now, because it is already over, or because there is no such planned message.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+export type SetAgentScopedUserChatTimeoutPausedStateResult =
+    | { readonly isApplied: true; readonly plannedMessage: UserChatTimeoutRecord }
+    | { readonly isApplied: false; readonly plannedMessage: UserChatTimeoutRecord | null };
+
+/**
+ * Options for holding one planned message back, or letting it go again.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+export type SetAgentScopedUserChatTimeoutPausedStateOptions = {
+    /**
+     * Owning user, or `undefined` to span every user of the agent.
+     */
+    readonly userId?: number;
+    readonly agentPermanentId: string;
+    readonly timeoutId: string;
+
+    /**
+     * Whether the planned message should be held back from waking its agent.
+     */
+    readonly isPaused: boolean;
+};
+
+/**
+ * Holds one planned message back from waking its agent, or lets it go again.
+ *
+ * This is the one place pausing is written and the worker is told about it, so a single planned
+ * message paused from the admin manager and a whole agent paused at once behave identically.
+ *
+ * @param options - Planned message and the state it should take.
+ * @returns Whether the planned message took the requested state, with the stored planned message.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+export async function setAgentScopedUserChatTimeoutPausedState(
+    options: SetAgentScopedUserChatTimeoutPausedStateOptions,
+): Promise<SetAgentScopedUserChatTimeoutPausedStateResult> {
+    const updatedPlannedMessage = await updateAgentScopedUserChatTimeout({
+        userId: options.userId,
+        agentPermanentId: options.agentPermanentId,
+        timeoutId: options.timeoutId,
+        patch: {
+            pausedAt: options.isPaused ? new Date().toISOString() : null,
+        },
+    });
+
+    if (!updatedPlannedMessage || Boolean(updatedPlannedMessage.pausedAt) !== options.isPaused) {
+        return { isApplied: false, plannedMessage: updatedPlannedMessage };
+    }
+
+    notifyUserChatTimeoutScheduleChanged(updatedPlannedMessage);
+
+    return { isApplied: true, plannedMessage: updatedPlannedMessage };
+}

package/apps/agents-server/src/utils/userChatTimeout/userChatTimeoutStore/createUserChatTimeout.ts

@@ -1,6 +1,20 @@
 import type { Json } from '@/src/database/schema';
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../../src/errors/ParseError';
 import { $randomBase58 } from '../../../../../../src/utils/random/$randomBase58';
-import type { CreateUserChatTimeoutOptions, UserChatTimeoutInsert, UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
+import type {
+    CreateUserChatTimeoutOptions,
+    UserChatTimeoutInsert,
+    UserChatTimeoutRecord,
+    UserChatTimeoutRow,
+} from '../UserChatTimeoutRecord';
+import {
+    normalizePlannedMessageCronExpression,
+    normalizePlannedMessageDateIso,
+    normalizePlannedMessageMaxRunCount,
+    resolvePlannedMessageDueAt,
+    type PlannedMessageSchedule,
+} from '../plannedMessageSchedule';
 import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
 import { mapUserChatTimeoutRow } from './mapUserChatTimeoutRow';
 import { normalizeRecurrenceIntervalMs } from './normalizeRecurrenceIntervalMs';
@@ -38,8 +52,9 @@ export async function createUserChatTimeout(options: CreateUserChatTimeoutOption
     const nowIso = new Date().toISOString();
     const timeoutId =
         options.id || `${USER_CHAT_TIMEOUT_ID_PREFIX}${$randomBase58(GENERATED_USER_CHAT_TIMEOUT_ID_LENGTH)}`;
-    const dueAt = options.dueAt || new Date(Date.now() + options.durationMs).toISOString();
-    const recurrenceIntervalMs = normalizeRecurrenceIntervalMs(options.recurrenceIntervalMs);
+    const schedule = createUserChatTimeoutSchedule(options);
+    const dueAt = options.dueAt || resolveCreatedUserChatTimeoutDueAtIso(schedule, options.durationMs ?? null);
+    const durationMs = options.durationMs ?? Math.max(0, Date.parse(dueAt) - Date.parse(nowIso));
     const userChatTimeoutTable = await provideUserChatTimeoutTable();
     const insertPayload: UserChatTimeoutInsert = {
         id: timeoutId,
@@ -51,9 +66,13 @@ export async function createUserChatTimeout(options: CreateUserChatTimeoutOption
         status: 'QUEUED',
         message: options.message || null,
         parameters: (options.parameters || {}) satisfies Record<string, unknown> as Json,
-        durationMs: options.durationMs,
+        durationMs,
         dueAt,
-        recurrenceIntervalMs,
+        recurrenceIntervalMs: schedule.recurrenceIntervalMs,
+        cronExpression: schedule.cronExpression,
+        startsAt: schedule.startsAt,
+        endsAt: schedule.endsAt,
+        maxRunCount: schedule.maxRunCount,
         queuedAt: nowIso,
         pausedAt: null,
         attemptCount: 0,
@@ -77,3 +96,55 @@ export async function createUserChatTimeout(options: CreateUserChatTimeoutOption
 
     return mapUserChatTimeoutRow(data as UserChatTimeoutRow);
 }
+
+/**
+ * Collects the recurrence rule of one newly created timeout.
+ *
+ * @param options - Input of the created timeout.
+ * @returns Normalized recurrence rule.
+ *
+ * @private function of createUserChatTimeout
+ */
+function createUserChatTimeoutSchedule(options: CreateUserChatTimeoutOptions): PlannedMessageSchedule {
+    return {
+        recurrenceIntervalMs: normalizeRecurrenceIntervalMs(options.recurrenceIntervalMs),
+        cronExpression: normalizePlannedMessageCronExpression(options.cronExpression),
+        startsAt: normalizePlannedMessageDateIso(options.startsAt),
+        endsAt: normalizePlannedMessageDateIso(options.endsAt),
+        maxRunCount: normalizePlannedMessageMaxRunCount(options.maxRunCount),
+    };
+}
+
+/**
+ * Resolves when one newly created timeout fires for the first time.
+ *
+ * @param schedule - Recurrence rule of the created timeout.
+ * @param fallbackDelayMs - Delay used by a timeout that does not repeat.
+ * @returns ISO time of the first wake-up.
+ *
+ * @private function of createUserChatTimeout
+ */
+function resolveCreatedUserChatTimeoutDueAtIso(
+    schedule: PlannedMessageSchedule,
+    fallbackDelayMs: number | null,
+): string {
+    const dueAtDate = resolvePlannedMessageDueAt({
+        schedule,
+        completedRunCount: 0,
+        afterDate: new Date(),
+        fallbackDelayMs,
+    });
+
+    if (dueAtDate === null) {
+        throw new ParseError(
+            spaceTrim(`
+                This planned message would never wake the agent.
+
+                - Its schedule is already over, for example because \`endsAt\` is in the past or \`maxRunCount\` is exhausted.
+                - Plan a schedule with at least one wake-up still ahead.
+            `),
+        );
+    }
+
+    return dueAtDate.toISOString();
+}

package/apps/agents-server/src/utils/userChatTimeout/userChatTimeoutStore/listAllUserChatTimeouts.ts

@@ -0,0 +1,37 @@
+import type {
+    ListAllUserChatTimeoutsOptions,
+    UserChatTimeoutRecord,
+    UserChatTimeoutRow,
+} from '../UserChatTimeoutRecord';
+import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
+import { mapUserChatTimeoutRow } from './mapUserChatTimeoutRow';
+import { provideUserChatTimeoutTable } from './provideUserChatTimeoutTable';
+
+/**
+ * Lists the timeouts of every agent and every user on this server, newest first.
+ *
+ * This is the server-wide counterpart of `listAgentUserChatTimeouts`, used by the admin
+ * planned-message manager which spans all agents instead of one.
+ *
+ * @private function of userChatTimeoutStore
+ */
+export async function listAllUserChatTimeouts(
+    options: ListAllUserChatTimeoutsOptions,
+): Promise<Array<UserChatTimeoutRecord>> {
+    const userChatTimeoutTable = await provideUserChatTimeoutTable();
+    const { data, error } = await userChatTimeoutTable
+        .select('*')
+        .order('updatedAt', { ascending: false })
+        .order('createdAt', { ascending: false })
+        .range(0, Math.max(0, options.limit - 1));
+
+    if (error) {
+        if (isMissingUserChatTimeoutRelationError(error)) {
+            return [];
+        }
+
+        throw new Error(`Failed to list user chat timeouts of every agent: ${error.message}`);
+    }
+
+    return ((data || []) as Array<UserChatTimeoutRow>).map(mapUserChatTimeoutRow);
+}

package/apps/agents-server/src/utils/userChatTimeout/userChatTimeoutStore/mapUserChatTimeoutRow.ts

@@ -1,4 +1,9 @@
 import type { UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
+import {
+    normalizePlannedMessageCronExpression,
+    normalizePlannedMessageDateIso,
+    normalizePlannedMessageMaxRunCount,
+} from '../plannedMessageSchedule';
 import { normalizeRecurrenceIntervalMs } from './normalizeRecurrenceIntervalMs';
 import { normalizeUserChatTimeoutParameters } from './normalizeUserChatTimeoutParameters';
 
@@ -22,6 +27,10 @@ export function mapUserChatTimeoutRow(row: UserChatTimeoutRow): UserChatTimeoutR
         durationMs: row.durationMs,
         dueAt: row.dueAt,
         recurrenceIntervalMs: normalizeRecurrenceIntervalMs(row.recurrenceIntervalMs),
+        cronExpression: normalizePlannedMessageCronExpression(row.cronExpression),
+        startsAt: normalizePlannedMessageDateIso(row.startsAt),
+        endsAt: normalizePlannedMessageDateIso(row.endsAt),
+        maxRunCount: normalizePlannedMessageMaxRunCount(row.maxRunCount),
         queuedAt: row.queuedAt,
         startedAt: row.startedAt,
         completedAt: row.completedAt,