@promptbook/cli 0.114.0-3 → 0.114.0-31

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';