@promptbook/cli 0.114.0-3 → 0.114.0-30

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

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) {