@promptbook/cli 0.114.0-5 → 0.114.0-50

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

@@ -2,6 +2,14 @@ import { LimitReachedError } from '@promptbook-local/core';
 import type { ChatMessage } from '@promptbook-local/types';
 import { serializeError, spaceTrim } from '@promptbook-local/utils';
 import { $randomBase58 } from '../../../../../src/utils/random/$randomBase58';
+import { appendAgentGoalChatNote } from '../agentGoalChat/appendAgentGoalChatNote';
+import { isAgentGoalChatId } from '../agentGoalChat/agentGoalChatIdentity';
+import {
+    createAgentGoalChatCancelledPlannedMessageNoteContent,
+    createAgentGoalChatPlannedMessageNoteContent,
+    createAgentGoalChatUpdatedPlannedMessageNoteContent,
+    type AgentGoalChatPlannedMessageNoteOptions,
+} from '../agentGoalChat/createAgentGoalChatNoteContent';
 import { getToolUsageLimits } from '../toolUsageLimits';
 import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
 import { sendUserChatPushNotification } from '../sendUserChatPushNotification';
@@ -11,8 +19,13 @@ import { getUserChatJobByClientMessageId } from '../userChat/getUserChatJobByCli
 import { mutateUserChat } from '../userChat/mutateUserChat';
 import { triggerUserChatJobWorker } from '../userChat/triggerUserChatJobWorker';
 import { runWithTaskTerminalCapture } from '../taskTerminal/runWithTaskTerminalCapture';
-import type { UserChatTimeoutParameters, UserChatTimeoutRecord } from './UserChatTimeoutRecord';
+import type {
+    UpdateAgentScopedUserChatTimeoutOptions,
+    UserChatTimeoutParameters,
+    UserChatTimeoutRecord,
+} from './UserChatTimeoutRecord';
 import { createTimeoutWakeUpMessage } from './createTimeoutWakeUpMessage';
+import { hasPlannedMessageRecurrence, isPlannedMessageScheduleFinished } from './plannedMessageSchedule';
 import {
     cancelUserChatTimeout,
     claimNextDueUserChatTimeout,
@@ -24,6 +37,8 @@ import {
     markUserChatTimeoutCompleted,
     markUserChatTimeoutFailed,
     recoverExpiredRunningUserChatTimeouts,
+    repeatFiredUserChatTimeout,
+    updateAgentScopedUserChatTimeout,
 } from './userChatTimeoutStore';
 
 /**
@@ -84,8 +99,12 @@ export async function scheduleThreadScopedUserChatTimeout(options: {
     readonly userId: number;
     readonly agentPermanentId: string;
     readonly chatId: string;
-    readonly durationMs: number;
+    readonly durationMs?: number;
     readonly recurrenceIntervalMs?: number | null;
+    readonly cronExpression?: string | null;
+    readonly startsAt?: string | null;
+    readonly endsAt?: string | null;
+    readonly maxRunCount?: number | null;
     readonly message?: string;
     readonly parameters?: UserChatTimeoutParameters;
 }): Promise<UserChatTimeoutRecord> {
@@ -108,6 +127,10 @@ export async function scheduleThreadScopedUserChatTimeout(options: {
         chatId: options.chatId,
         durationMs: options.durationMs,
         recurrenceIntervalMs: options.recurrenceIntervalMs,
+        cronExpression: options.cronExpression,
+        startsAt: options.startsAt,
+        endsAt: options.endsAt,
+        maxRunCount: options.maxRunCount,
         message: options.message,
         parameters: options.parameters,
     });
@@ -119,6 +142,7 @@ export async function scheduleThreadScopedUserChatTimeout(options: {
         durationMs: timeout.durationMs,
     });
 
+    await recordAgentGoalChatPlannedMessageNote(timeout);
     scheduleUserChatTimeoutLocalWakeup(timeout);
 
     return timeout;
@@ -130,6 +154,8 @@ export async function scheduleThreadScopedUserChatTimeout(options: {
  * @private internal utility of userChatTimeout
  */
 export async function cancelScheduledUserChatTimeout(timeoutId: string): Promise<UserChatTimeoutRecord | null> {
+    // Note: Cancelling an already-cancelled timeout is a no-op, and must not repeat its goal-chat note
+    const timeoutBeforeCancellation = await getUserChatTimeoutById(timeoutId);
     const cancelledTimeout = await cancelUserChatTimeout(timeoutId);
     clearUserChatTimeoutLocalWakeup(timeoutId);
 
@@ -140,11 +166,105 @@ export async function cancelScheduledUserChatTimeout(timeoutId: string): Promise
             status: cancelledTimeout.status,
             cancelRequestedAt: cancelledTimeout.cancelRequestedAt,
         });
+
+        if (!timeoutBeforeCancellation?.cancelRequestedAt) {
+            await recordAgentGoalChatCancelledPlannedMessageNote(cancelledTimeout);
+        }
     }
 
     return cancelledTimeout;
 }
 
+/**
+ * Updates the schedule of one planned message and keeps every wake-up surface in sync.
+ *
+ * This is the counterpart of scheduling and cancelling: one planned message can be re-planned without
+ * losing its identity, so the agent keeps the `timeoutId` it already knows and the goal chat records
+ * the new schedule.
+ *
+ * @param options - Scoped timeout identity together with the schedule patch.
+ * @returns The updated timeout, or `null` when there is no such planned message.
+ *
+ * @private internal utility of userChatTimeout
+ */
+export async function updateScheduledUserChatTimeout(
+    options: UpdateAgentScopedUserChatTimeoutOptions,
+): Promise<UserChatTimeoutRecord | null> {
+    const updatedTimeout = await updateAgentScopedUserChatTimeout(options);
+
+    if (!updatedTimeout) {
+        return null;
+    }
+
+    console.info('[user-chat-timeout]', 'update', {
+        chatId: updatedTimeout.chatId,
+        timeoutId: updatedTimeout.timeoutId,
+        dueAt: updatedTimeout.dueAt,
+        recurrenceIntervalMs: updatedTimeout.recurrenceIntervalMs,
+        cronExpression: updatedTimeout.cronExpression,
+    });
+
+    notifyUserChatTimeoutScheduleChanged(updatedTimeout);
+    await recordAgentGoalChatPlannedMessageNote(updatedTimeout, createAgentGoalChatUpdatedPlannedMessageNoteContent);
+
+    return updatedTimeout;
+}
+
+/**
+ * Mirrors one planned message and its schedule into the goal chat of the owning agent.
+ *
+ * Planned messages can be created from any chat, but the agent's own thread is where all of them
+ * become visible, so the goal chat always shows the full plan.
+ *
+ * @param timeout - Planned message that was just scheduled or re-planned.
+ * @param createNoteContent - Note wording of the recorded schedule change.
+ *
+ * @private internal utility of userChatTimeout
+ */
+async function recordAgentGoalChatPlannedMessageNote(
+    timeout: UserChatTimeoutRecord,
+    createNoteContent: (
+        options: AgentGoalChatPlannedMessageNoteOptions,
+    ) => string = createAgentGoalChatPlannedMessageNoteContent,
+): Promise<void> {
+    await appendAgentGoalChatNote({
+        agentPermanentId: timeout.agentPermanentId,
+        content: createNoteContent({
+            timeoutId: timeout.timeoutId,
+            dueAt: timeout.dueAt,
+            intervalMs: timeout.recurrenceIntervalMs,
+            cronExpression: timeout.cronExpression,
+            startsAt: timeout.startsAt,
+            endsAt: timeout.endsAt,
+            maxRunCount: timeout.maxRunCount,
+            runCount: timeout.runCount,
+            message: timeout.message,
+        }),
+    }).catch((error) => {
+        console.error('[user-chat-timeout]', 'goal_chat_planned_note_failed', {
+            timeoutId: timeout.timeoutId,
+            error: serializeError(error as Error),
+        });
+    });
+}
+
+/**
+ * Mirrors one cancelled planned message into the goal chat of the owning agent.
+ *
+ * @private internal utility of userChatTimeout
+ */
+async function recordAgentGoalChatCancelledPlannedMessageNote(timeout: UserChatTimeoutRecord): Promise<void> {
+    await appendAgentGoalChatNote({
+        agentPermanentId: timeout.agentPermanentId,
+        content: createAgentGoalChatCancelledPlannedMessageNoteContent({ timeoutId: timeout.timeoutId }),
+    }).catch((error) => {
+        console.error('[user-chat-timeout]', 'goal_chat_cancelled_note_failed', {
+            timeoutId: timeout.timeoutId,
+            error: serializeError(error as Error),
+        });
+    });
+}
+
 /**
  * Retained compatibility no-op for call sites that previously started a polling loop.
  *
@@ -246,6 +366,29 @@ async function processClaimedUserChatTimeout(timeout: UserChatTimeoutRecord): Pr
             return;
         }
 
+        if (
+            isPlannedMessageScheduleFinished({
+                schedule: latestTimeout,
+                completedRunCount: latestTimeout.runCount,
+                atDate: new Date(),
+            })
+        ) {
+            // Note: A wake-up delayed past the ending date of its plan is dropped instead of fired late
+            await markUserChatTimeoutCancelled(
+                latestTimeout.timeoutId,
+                'Planned message reached the end of its schedule.',
+            );
+            console.info('[user-chat-timeout]', 'schedule_finished', {
+                chatId: latestTimeout.chatId,
+                timeoutId: latestTimeout.timeoutId,
+                dueAt: latestTimeout.dueAt,
+                endsAt: latestTimeout.endsAt,
+                runCount: latestTimeout.runCount,
+                maxRunCount: latestTimeout.maxRunCount,
+            });
+            return;
+        }
+
         const chat = await getUserChat({
             userId: latestTimeout.userId,
             agentPermanentId: latestTimeout.agentPermanentId,
@@ -277,7 +420,7 @@ async function processClaimedUserChatTimeout(timeout: UserChatTimeoutRecord): Pr
             return;
         }
 
-        const timeoutClientMessageId = createTimeoutClientMessageId(latestTimeout.timeoutId);
+        const timeoutClientMessageId = createTimeoutClientMessageId(latestTimeout);
         let queuedJob = await getUserChatJobByClientMessageId({
             userId: latestTimeout.userId,
             agentPermanentId: latestTimeout.agentPermanentId,
@@ -295,8 +438,15 @@ async function processClaimedUserChatTimeout(timeout: UserChatTimeoutRecord): Pr
                     messageContent: createTimeoutWakeUpMessage({
                         timeoutId: latestTimeout.timeoutId,
                         durationMs: latestTimeout.durationMs,
+                        intervalMs: latestTimeout.recurrenceIntervalMs,
+                        cronExpression: latestTimeout.cronExpression,
+                        startsAt: latestTimeout.startsAt,
+                        endsAt: latestTimeout.endsAt,
+                        maxRunCount: latestTimeout.maxRunCount,
+                        runCount: latestTimeout.runCount + 1,
                         message: latestTimeout.message,
                     }),
+                    messageSender: isAgentGoalChatId(latestTimeout.chatId) ? 'AGENT' : 'USER',
                     parameters: latestTimeout.parameters,
                 });
                 queuedJob = enqueuedTurn.job;
@@ -336,42 +486,19 @@ async function processClaimedUserChatTimeout(timeout: UserChatTimeoutRecord): Pr
             return;
         }
 
-        const completedTimeout = await markUserChatTimeoutCompleted(latestTimeout.timeoutId);
-
-        if (!completedTimeout || completedTimeout.status !== 'COMPLETED') {
-            console.info('[user-chat-timeout]', 'skip_recurrence_non_completed', {
-                chatId: latestTimeout.chatId,
-                timeoutId: latestTimeout.timeoutId,
-                resultingStatus: completedTimeout?.status || null,
-            });
-            return;
-        }
-
         try {
-            const recurringTimeout = await scheduleRecurringUserChatTimeout(completedTimeout);
-
-            if (recurringTimeout) {
-                console.info('[user-chat-timeout]', 'rescheduled', {
-                    chatId: recurringTimeout.chatId,
-                    previousTimeoutId: latestTimeout.timeoutId,
-                    timeoutId: recurringTimeout.timeoutId,
-                    dueAt: recurringTimeout.dueAt,
-                    recurrenceIntervalMs: recurringTimeout.recurrenceIntervalMs,
-                });
-            }
-        } catch (recurrenceError) {
-            const recurrenceReason =
-                recurrenceError instanceof Error
-                    ? recurrenceError.message
-                    : 'Failed to schedule recurring timeout.';
+            await finishFiredUserChatTimeout(latestTimeout);
+        } catch (repetitionError) {
+            const repetitionReason =
+                repetitionError instanceof Error ? repetitionError.message : 'Failed to repeat the planned message.';
             await appendUserChatTimeoutWarningMessage(
                 latestTimeout,
-                `Recurring schedule failed: ${recurrenceReason}`,
+                `Repeating schedule failed: ${repetitionReason}`,
             ).catch(() => undefined);
-            console.error('[user-chat-timeout]', 'recurrence_schedule_failed', {
+            console.error('[user-chat-timeout]', 'repeat_failed', {
                 chatId: latestTimeout.chatId,
                 timeoutId: latestTimeout.timeoutId,
-                error: serializeError(recurrenceError as Error),
+                error: serializeError(repetitionError as Error),
             });
         }
 
@@ -398,7 +525,10 @@ async function processClaimedUserChatTimeout(timeout: UserChatTimeoutRecord): Pr
  *
  * @private internal utility of userChatTimeout
  */
-async function appendUserChatTimeoutWarningMessage(timeout: UserChatTimeoutRecord, failureReason: string): Promise<void> {
+async function appendUserChatTimeoutWarningMessage(
+    timeout: UserChatTimeoutRecord,
+    failureReason: string,
+): Promise<void> {
     const chat = await getUserChat({
         userId: timeout.userId,
         agentPermanentId: timeout.agentPermanentId,
@@ -498,33 +628,54 @@ function clearUserChatTimeoutLocalWakeup(timeoutId: string): void {
 }
 
 /**
- * Creates the next queued row for recurring timeouts after one successful fire.
+ * Closes one fired timeout, keeping a repeating planned message armed for its next wake-up.
+ *
+ * A repeating timeout is the durable counterpart of `setInterval`, so it is re-armed in place
+ * instead of being completed: it keeps one row, one identity, and one cancellation point. A
+ * timeout that does not repeat, one whose schedule is over — because it ran as many times as it was
+ * planned to run or its ending date passed — and one that was cancelled while it was firing all
+ * become terminal, so a finished plan disappears from everything the agent is shown.
+ *
+ * @param firedTimeout - Timeout whose wake-up turn was just queued.
  *
  * @private internal utility of userChatTimeout
  */
-async function scheduleRecurringUserChatTimeout(
-    completedTimeout: UserChatTimeoutRecord,
-): Promise<UserChatTimeoutRecord | null> {
-    const recurrenceIntervalMs = completedTimeout.recurrenceIntervalMs;
+async function finishFiredUserChatTimeout(firedTimeout: UserChatTimeoutRecord): Promise<void> {
+    if (hasPlannedMessageRecurrence(firedTimeout)) {
+        const repeatedTimeout = await repeatFiredUserChatTimeout(firedTimeout.timeoutId);
+
+        if (repeatedTimeout?.status === 'QUEUED') {
+            console.info('[user-chat-timeout]', 'repeated', {
+                chatId: repeatedTimeout.chatId,
+                timeoutId: repeatedTimeout.timeoutId,
+                dueAt: repeatedTimeout.dueAt,
+                recurrenceIntervalMs: repeatedTimeout.recurrenceIntervalMs,
+                cronExpression: repeatedTimeout.cronExpression,
+                runCount: repeatedTimeout.runCount,
+                maxRunCount: repeatedTimeout.maxRunCount,
+            });
+            scheduleUserChatTimeoutLocalWakeup(repeatedTimeout);
+            return;
+        }
 
-    if (typeof recurrenceIntervalMs !== 'number' || !Number.isFinite(recurrenceIntervalMs) || recurrenceIntervalMs <= 0) {
-        return null;
+        // Note: A planned message that could not be re-armed, for example because its schedule is over or
+        //       because it was cancelled while it was firing, is closed like a timeout that never repeated
+        console.info('[user-chat-timeout]', 'skip_repeat', {
+            chatId: firedTimeout.chatId,
+            timeoutId: firedTimeout.timeoutId,
+            resultingStatus: repeatedTimeout?.status || null,
+        });
     }
 
-    const nextDueAtIso = new Date(Date.now() + Math.floor(recurrenceIntervalMs)).toISOString();
-    const nextTimeout = await createUserChatTimeout({
-        userId: completedTimeout.userId,
-        agentPermanentId: completedTimeout.agentPermanentId,
-        chatId: completedTimeout.chatId,
-        durationMs: Math.floor(recurrenceIntervalMs),
-        recurrenceIntervalMs: Math.floor(recurrenceIntervalMs),
-        dueAt: nextDueAtIso,
-        message: completedTimeout.message || undefined,
-        parameters: completedTimeout.parameters,
-    });
+    const completedTimeout = await markUserChatTimeoutCompleted(firedTimeout.timeoutId);
 
-    scheduleUserChatTimeoutLocalWakeup(nextTimeout);
-    return nextTimeout;
+    if (!completedTimeout || completedTimeout.status !== 'COMPLETED') {
+        console.info('[user-chat-timeout]', 'skip_completion_non_completed', {
+            chatId: firedTimeout.chatId,
+            timeoutId: firedTimeout.timeoutId,
+            resultingStatus: completedTimeout?.status || null,
+        });
+    }
 }
 
 /**
@@ -545,12 +696,24 @@ function shouldDisableBackgroundWorkerLoop(): boolean {
 }
 
 /**
- * Builds the synthetic client message id used for timeout wake-ups.
+ * Builds the synthetic client message id used for one timeout wake-up.
+ *
+ * A repeating timeout keeps its identity across firings, so the id also carries how many times it
+ * already fired: retrying the very same firing stays idempotent, while the next repetition still
+ * queues its own wake-up turn.
+ *
+ * @param timeout - Timeout that is firing.
+ * @returns Client message id of this wake-up.
  *
  * @private internal utility of userChatTimeout
  */
-function createTimeoutClientMessageId(timeoutId: string): string {
-    return `${USER_CHAT_TIMEOUT_CLIENT_MESSAGE_ID_PREFIX}${timeoutId}`;
+function createTimeoutClientMessageId(timeout: Pick<UserChatTimeoutRecord, 'timeoutId' | 'runCount'>): string {
+    // Note: The first firing keeps the historical id, so wake-ups queued before repeating support stay deduplicated
+    if (timeout.runCount === 0) {
+        return `${USER_CHAT_TIMEOUT_CLIENT_MESSAGE_ID_PREFIX}${timeout.timeoutId}`;
+    }
+
+    return `${USER_CHAT_TIMEOUT_CLIENT_MESSAGE_ID_PREFIX}${timeout.timeoutId}:${timeout.runCount}`;
 }
 
 /**

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

@@ -14,6 +14,7 @@ export {
     getUserChatTimeout,
     getUserChatTimeoutById,
     listAgentUserChatTimeouts,
+    listAllUserChatTimeouts,
     listUserChatTimeouts,
     markUserChatTimeoutCancelled,
     markUserChatTimeoutCompleted,
@@ -30,13 +31,28 @@ export {
     notifyUserChatTimeoutScheduleChanged,
     runUserChatTimeoutWorkerTick,
     scheduleThreadScopedUserChatTimeout,
+    updateScheduledUserChatTimeout,
 } from './userChatTimeout/userChatTimeoutWorker';
+export {
+    hasPlannedMessageRecurrence,
+    isPlannedMessageScheduleFinished,
+    MINIMUM_PLANNED_MESSAGE_INTERVAL_MS,
+    parsePlannedMessageSchedule,
+    resolvePlannedMessageDueAt,
+} from './userChatTimeout/plannedMessageSchedule';
+export type { PlannedMessageSchedule, PlannedMessageScheduleInput } from './userChatTimeout/plannedMessageSchedule';
+export { setAgentScopedUserChatTimeoutPausedState } from './userChatTimeout/setAgentScopedUserChatTimeoutPausedState';
+export type {
+    SetAgentScopedUserChatTimeoutPausedStateOptions,
+    SetAgentScopedUserChatTimeoutPausedStateResult,
+} from './userChatTimeout/setAgentScopedUserChatTimeoutPausedState';
 export { triggerUserChatTimeoutWorker } from './userChatTimeout/triggerUserChatTimeoutWorker';
 export type {
     CreateUserChatTimeoutOptions,
     GetAgentScopedUserChatTimeoutOptions,
     GetUserChatTimeoutOptions,
     ListAgentUserChatTimeoutsOptions,
+    ListAllUserChatTimeoutsOptions,
     ListUserChatTimeoutsOptions,
     UpdateAgentScopedUserChatTimeoutOptions,
     UpdateAgentScopedUserChatTimeoutPatch,