@promptbook/cli 0.114.0-2 → 0.114.0-21

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/claimNextDueUserChatTimeout.ts

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
 import type { UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
@@ -32,31 +33,33 @@ export async function claimNextDueUserChatTimeout(
 
     try {
         claimedRows = await sql.raw<Array<UserChatTimeoutRow>>(
-            `
-                WITH candidate AS (
-                    SELECT timeout."id"
-                    FROM ${tableIdentifier} timeout
-                    WHERE timeout."status" = 'QUEUED'
-                      AND timeout."cancelRequestedAt" IS NULL
-                      AND timeout."pausedAt" IS NULL
-                      AND timeout."dueAt" <= CURRENT_TIMESTAMP
-                      ${preferredTimeoutClause}
-                    ORDER BY timeout."dueAt" ASC, timeout."createdAt" ASC
-                    LIMIT 1
-                    FOR UPDATE SKIP LOCKED
-                )
-                UPDATE ${tableIdentifier} timeout
-                SET
-                    "status" = 'RUNNING',
-                    "updatedAt" = CURRENT_TIMESTAMP,
-                    "startedAt" = COALESCE(timeout."startedAt", CURRENT_TIMESTAMP),
-                    "leaseExpiresAt" = CURRENT_TIMESTAMP + ($1 * INTERVAL '1 millisecond'),
-                    "attemptCount" = timeout."attemptCount" + 1,
-                    "failureReason" = NULL
-                FROM candidate
-                WHERE timeout."id" = candidate."id"
-                RETURNING timeout.*
-            `,
+            spaceTrim(
+                (block) => `
+                    WITH candidate AS (
+                        SELECT timeout."id"
+                        FROM ${tableIdentifier} timeout
+                        WHERE timeout."status" = 'QUEUED'
+                          AND timeout."cancelRequestedAt" IS NULL
+                          AND timeout."pausedAt" IS NULL
+                          AND timeout."dueAt" <= CURRENT_TIMESTAMP
+                          ${block(preferredTimeoutClause)}
+                        ORDER BY timeout."dueAt" ASC, timeout."createdAt" ASC
+                        LIMIT 1
+                        FOR UPDATE SKIP LOCKED
+                    )
+                    UPDATE ${tableIdentifier} timeout
+                    SET
+                        "status" = 'RUNNING',
+                        "updatedAt" = CURRENT_TIMESTAMP,
+                        "startedAt" = COALESCE(timeout."startedAt", CURRENT_TIMESTAMP),
+                        "leaseExpiresAt" = CURRENT_TIMESTAMP + ($1 * INTERVAL '1 millisecond'),
+                        "attemptCount" = timeout."attemptCount" + 1,
+                        "failureReason" = NULL
+                    FROM candidate
+                    WHERE timeout."id" = candidate."id"
+                    RETURNING timeout.*
+                `,
+            ),
             values,
         );
     } catch (error) {

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/getAgentScopedUserChatTimeout.ts

@@ -16,12 +16,16 @@ export async function getAgentScopedUserChatTimeout(
     options: GetAgentScopedUserChatTimeoutOptions,
 ): Promise<UserChatTimeoutRecord | null> {
     const userChatTimeoutTable = await provideUserChatTimeoutTable();
-    const { data, error } = await userChatTimeoutTable
+    let query = userChatTimeoutTable
         .select('*')
         .eq('id', options.timeoutId)
-        .eq('userId', options.userId)
-        .eq('agentPermanentId', options.agentPermanentId)
-        .maybeSingle();
+        .eq('agentPermanentId', options.agentPermanentId);
+
+    if (typeof options.userId === 'number') {
+        query = query.eq('userId', options.userId);
+    }
+
+    const { data, error } = await query.maybeSingle();
 
     if (error) {
         if (isMissingUserChatTimeoutRelationError(error)) {

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

@@ -14,11 +14,14 @@ export async function listAgentUserChatTimeouts(
     const userChatTimeoutTable = await provideUserChatTimeoutTable();
     let query = userChatTimeoutTable
         .select('*')
-        .eq('userId', options.userId)
         .eq('agentPermanentId', options.agentPermanentId)
         .order('updatedAt', { ascending: false })
         .order('createdAt', { ascending: false });
 
+    if (typeof options.userId === 'number') {
+        query = query.eq('userId', options.userId);
+    }
+
     if (options.statuses && options.statuses.length > 0) {
         query = query.in('status', options.statuses);
     }

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,

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

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { $provideClientSql } from '@/src/database/$provideClientSql';
 import { isAgentsServerSqliteMode } from '@/src/database/agentsServerDatabaseMode';
 import { getUserChatTimeoutTableName } from './getUserChatTimeoutTableName';
@@ -21,7 +22,7 @@ export async function recoverExpiredRunningUserChatTimeouts(): Promise<number> {
 
     try {
         recoveredRows = await sql.raw<Array<{ id: string }>>(
-            `
+            spaceTrim(`
                 UPDATE ${tableIdentifier}
                 SET
                     "status" = CASE
@@ -46,7 +47,7 @@ export async function recoverExpiredRunningUserChatTimeouts(): Promise<number> {
                   AND "leaseExpiresAt" IS NOT NULL
                   AND "leaseExpiresAt" < CURRENT_TIMESTAMP
                 RETURNING "id"
-            `,
+            `),
         );
     } catch (error) {
         rethrowUnlessMissingUserChatTimeoutRelation(error);

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

@@ -0,0 +1,84 @@
+import { markTaskTerminalLogFinished } from '../../taskTerminal/taskTerminalLog';
+import type { UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
+import { resolvePlannedMessageDueAt } from '../plannedMessageSchedule';
+import { getUserChatTimeoutById } from './getUserChatTimeoutById';
+import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
+import { mapUserChatTimeoutRow } from './mapUserChatTimeoutRow';
+import { provideUserChatTimeoutTable } from './provideUserChatTimeoutTable';
+
+/**
+ * Re-arms one fired repeating timeout for its next wake-up.
+ *
+ * A repeating timeout keeps its own row and identity across every firing, exactly like one
+ * `setInterval` handle: the agent that planned it can still cancel it by the very same `timeoutId`
+ * it saw before, and no firing can leave a duplicated schedule behind.
+ *
+ * @param timeoutId - Identifier of the timeout that has just fired.
+ * @returns The re-armed timeout, or `null` when the row must be completed instead because its schedule
+ *          is over — it does not repeat, it ran as many times as it was planned to run, its ending date
+ *          passed, or its repetitions were cancelled while it was firing.
+ *
+ * @private function of userChatTimeoutStore
+ */
+export async function repeatFiredUserChatTimeout(timeoutId: string): Promise<UserChatTimeoutRecord | null> {
+    const existingTimeout = await getUserChatTimeoutById(timeoutId);
+
+    if (!existingTimeout) {
+        return null;
+    }
+
+    if (existingTimeout.cancelRequestedAt) {
+        return null;
+    }
+
+    const nowDate = new Date();
+    // Note: The firing which is being closed already counts as one run of the planned message
+    const nextDueAtDate = resolvePlannedMessageDueAt({
+        schedule: existingTimeout,
+        completedRunCount: existingTimeout.runCount + 1,
+        afterDate: nowDate,
+    });
+
+    if (nextDueAtDate === null) {
+        return null;
+    }
+
+    const nowIso = nowDate.toISOString();
+    const userChatTimeoutTable = await provideUserChatTimeoutTable();
+    const { data, error } = await userChatTimeoutTable
+        .update({
+            status: 'QUEUED',
+            updatedAt: nowIso,
+            queuedAt: nowIso,
+            dueAt: nextDueAtDate.toISOString(),
+            startedAt: null,
+            completedAt: null,
+            leaseExpiresAt: null,
+            pausedAt: null,
+            failureReason: null,
+            runCount: existingTimeout.runCount + 1,
+            lastFiredAt: nowIso,
+        })
+        .eq('id', timeoutId)
+        .eq('status', existingTimeout.status)
+        .eq('runCount', existingTimeout.runCount)
+        .select('*')
+        .maybeSingle();
+
+    if (error) {
+        if (isMissingUserChatTimeoutRelationError(error)) {
+            return null;
+        }
+
+        throw new Error(`Failed to repeat user chat timeout "${timeoutId}": ${error.message}`);
+    }
+
+    // Note: One firing of a repeating timeout is one finished task, even though its row stays armed
+    markTaskTerminalLogFinished(timeoutId, { isSuccessful: true });
+
+    if (!data) {
+        return getUserChatTimeoutById(timeoutId);
+    }
+
+    return mapUserChatTimeoutRow(data as UserChatTimeoutRow);
+}

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

@@ -1,5 +1,14 @@
 import type { Json } from '@/src/database/schema';
-import type { UpdateAgentScopedUserChatTimeoutOptions, UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
+import type {
+    UpdateAgentScopedUserChatTimeoutOptions,
+    UserChatTimeoutRecord,
+    UserChatTimeoutRow,
+} from '../UserChatTimeoutRecord';
+import {
+    normalizePlannedMessageCronExpression,
+    normalizePlannedMessageDateIso,
+    normalizePlannedMessageMaxRunCount,
+} from '../plannedMessageSchedule';
 import { getAgentScopedUserChatTimeout } from './getAgentScopedUserChatTimeout';
 import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
 import { isTerminalUserChatTimeoutStatus } from './isTerminalUserChatTimeoutStatus';
@@ -51,6 +60,26 @@ export async function updateAgentScopedUserChatTimeout(
         hasPatchChanges = true;
     }
 
+    if (Object.prototype.hasOwnProperty.call(options.patch, 'cronExpression')) {
+        updatePayload.cronExpression = normalizePlannedMessageCronExpression(options.patch.cronExpression);
+        hasPatchChanges = true;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(options.patch, 'startsAt')) {
+        updatePayload.startsAt = normalizePlannedMessageDateIso(options.patch.startsAt);
+        hasPatchChanges = true;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(options.patch, 'endsAt')) {
+        updatePayload.endsAt = normalizePlannedMessageDateIso(options.patch.endsAt);
+        hasPatchChanges = true;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(options.patch, 'maxRunCount')) {
+        updatePayload.maxRunCount = normalizePlannedMessageMaxRunCount(options.patch.maxRunCount);
+        hasPatchChanges = true;
+    }
+
     if (Object.prototype.hasOwnProperty.call(options.patch, 'pausedAt')) {
         updatePayload.pausedAt = options.patch.pausedAt || null;
         hasPatchChanges = true;
@@ -74,14 +103,18 @@ export async function updateAgentScopedUserChatTimeout(
     }
 
     const userChatTimeoutTable = await provideUserChatTimeoutTable();
-    const { data, error } = await userChatTimeoutTable
+    let updateQuery = userChatTimeoutTable
         .update(updatePayload)
         .eq('id', options.timeoutId)
-        .eq('userId', options.userId)
         .eq('agentPermanentId', options.agentPermanentId)
-        .eq('status', existingTimeout.status)
-        .select('*')
-        .maybeSingle();
+        .eq('status', existingTimeout.status);
+
+    // Note: A planned message belongs to the agent, so the goal chat edits it without naming one user
+    if (typeof options.userId === 'number') {
+        updateQuery = updateQuery.eq('userId', options.userId);
+    }
+
+    const { data, error } = await updateQuery.select('*').maybeSingle();
 
     if (error) {
         if (isMissingUserChatTimeoutRelationError(error)) {

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

@@ -7,12 +7,14 @@ export { getAgentScopedUserChatTimeout } from './userChatTimeoutStore/getAgentSc
 export { getUserChatTimeout } from './userChatTimeoutStore/getUserChatTimeout';
 export { getUserChatTimeoutById } from './userChatTimeoutStore/getUserChatTimeoutById';
 export { listAgentUserChatTimeouts } from './userChatTimeoutStore/listAgentUserChatTimeouts';
+export { listAllUserChatTimeouts } from './userChatTimeoutStore/listAllUserChatTimeouts';
 export { listUserChatTimeoutActivities } from './userChatTimeoutStore/listUserChatTimeoutActivities';
 export { listUserChatTimeouts } from './userChatTimeoutStore/listUserChatTimeouts';
 export { markUserChatTimeoutCancelled } from './userChatTimeoutStore/markUserChatTimeoutCancelled';
 export { markUserChatTimeoutCompleted } from './userChatTimeoutStore/markUserChatTimeoutCompleted';
 export { markUserChatTimeoutFailed } from './userChatTimeoutStore/markUserChatTimeoutFailed';
 export { recoverExpiredRunningUserChatTimeouts } from './userChatTimeoutStore/recoverExpiredRunningUserChatTimeouts';
+export { repeatFiredUserChatTimeout } from './userChatTimeoutStore/repeatFiredUserChatTimeout';
 export { retryUserChatTimeout } from './userChatTimeoutStore/retryUserChatTimeout';
 export { updateAgentScopedUserChatTimeout } from './userChatTimeoutStore/updateAgentScopedUserChatTimeout';
 export { cancelUserChatTimeout } from './userChatTimeoutStore/cancelUserChatTimeout';