@promptbook/cli 0.114.0-13 → 0.114.0-18

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

@@ -4,7 +4,6 @@ import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
 import { isVoidPseudoAgentReference } from '../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
 import { ParseError } from '../../../../src/errors/ParseError';
-import { UnexpectedError } from '../../../../src/errors/UnexpectedError';
 import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { isValidAgentUrl } from '../../../../src/utils/validators/url/isValidAgentUrl';
 import {
@@ -15,6 +14,7 @@ import {
     type AgentReferenceResolutionIssue,
     consumeAgentReferenceResolutionIssues,
 } from './agentReferenceResolver/AgentReferenceResolutionIssue';
+import { collectExplicitFromCommitments, getExplicitFromCommitmentContent } from './explicitFromCommitment';
 import { type ImportAgentOptions } from './importAgent';
 import { importAgentWithFallback } from './importAgentWithFallback';
 
@@ -103,57 +103,6 @@ function insertNotesAfterTitle(agentSource: string_book, notes: ReadonlyArray<st
     return padBook(validateBook(nextLines.join('\n')));
 }
 
-/**
- * Returns the last explicit single-line commitment content for one commitment type.
- *
- * This lightweight parser is intentionally limited to the subset needed by
- * inheritance resolution so it stays safe to bundle into the Next.js proxy path.
- *
- * @param agentSource - Raw book source.
- * @param commitmentType - Commitment keyword to search for.
- * @returns Trimmed commitment content, empty string for a blank explicit commitment, or `undefined` when absent.
- */
-function getLastSingleLineCommitmentContent(agentSource: string_book, commitmentType: 'FROM'): string | undefined {
-    const commitmentPrefix = `${commitmentType} `;
-    const lines = agentSource.split(/\r?\n/);
-    let hasSeenTitle = false;
-    let isInsideCodeBlock = false;
-    let matchedContent: string | undefined;
-
-    for (const line of lines) {
-        const trimmedLine = line.trim();
-
-        if (!hasSeenTitle) {
-            if (!trimmedLine) {
-                continue;
-            }
-
-            hasSeenTitle = true;
-            continue;
-        }
-
-        if (trimmedLine.startsWith('```')) {
-            isInsideCodeBlock = !isInsideCodeBlock;
-            continue;
-        }
-
-        if (isInsideCodeBlock) {
-            continue;
-        }
-
-        if (trimmedLine === commitmentType) {
-            matchedContent = '';
-            continue;
-        }
-
-        if (trimmedLine.startsWith(commitmentPrefix)) {
-            matchedContent = trimmedLine.slice(commitmentPrefix.length).trim();
-        }
-    }
-
-    return matchedContent;
-}
-
 /**
  * Resolves the effective `FROM` parent URL using only lightweight commitment parsing.
  *
@@ -165,7 +114,7 @@ async function resolveParentAgentUrlFromCommitments(
     rawAgentSource: string_book,
     agentReferenceResolver?: AgentReferenceResolver,
 ): Promise<string_agent_url | null | undefined> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(rawAgentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(rawAgentSource);
 
     if (explicitFromContent === undefined) {
         return undefined;
@@ -285,6 +234,11 @@ type ResolvedParentAgentContext = {
      * Unresolved compact-reference issues captured while resolving `FROM`.
      */
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
+
+    /**
+     * Whether the effective parent closed the current lineage and must be materialized as `FROM @Null`.
+     */
+    readonly isCyclicFrom: boolean;
 };
 
 /**
@@ -357,6 +311,28 @@ type ResolvedFromCommitmentLine = {
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
 };
 
+/**
+ * One cycle found while following a source-resolution lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+type ResolutionCycle = {
+    /**
+     * Normalized URL that closes the cycle.
+     */
+    readonly normalizedReferenceUrl: string_agent_url;
+
+    /**
+     * URLs visited before the repeated reference was encountered.
+     */
+    readonly lineage: ReadonlyArray<string_agent_url>;
+
+    /**
+     * Position in `lineage` where the cycle begins.
+     */
+    readonly cycleStartIndex: number;
+};
+
 /**
  * Normalizes agent URLs used for cycle detection and lineage reporting.
  *
@@ -387,6 +363,30 @@ function createResolutionLineage(options?: ResolveInheritedAgentSourceOptions):
     return [...new Set(lineage.map(normalizeAgentUrl))];
 }
 
+/**
+ * Finds a cycle that would be closed by resolving one more agent reference.
+ *
+ * @param referenceUrl - Next agent reference to resolve.
+ * @param options - Current resolution options.
+ * @returns Cycle details, or `null` when the reference is not in the current lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+function findResolutionCycle(
+    referenceUrl: string_agent_url,
+    options?: ResolveInheritedAgentSourceOptions,
+): ResolutionCycle | null {
+    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
+    const lineage = createResolutionLineage(options);
+    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+
+    if (cycleStartIndex === -1) {
+        return null;
+    }
+
+    return { normalizedReferenceUrl, lineage, cycleStartIndex };
+}
+
 /**
  * Creates the shared import context used throughout one resolution pass.
  *
@@ -415,6 +415,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
  * @param hasExplicitFromCommitment - Whether the source explicitly declared `FROM`.
  * @param adamAgentUrl - Default Adam ancestor URL.
  * @param currentAgentUrl - Canonical URL of the source being resolved.
+ * @param currentAgentAliases - Additional URLs that identify the source being resolved.
  * @param agentSource - Raw source used for unexpected diagnostics.
  * @returns Effective parent URL or `null` when inheritance is disabled.
  */
@@ -423,6 +424,7 @@ function determineParentAgentUrl(
     hasExplicitFromCommitment: boolean,
     adamAgentUrl: string_agent_url,
     currentAgentUrl?: string_agent_url,
+    currentAgentAliases?: ReadonlyArray<string_agent_url>,
     agentSource?: string_book,
 ): string_agent_url | null {
     if (isValidAgentUrl(resolvedParentAgentUrl)) {
@@ -434,9 +436,14 @@ function determineParentAgentUrl(
     }
 
     if (resolvedParentAgentUrl === undefined || resolvedParentAgentUrl === null) {
-        return currentAgentUrl && normalizeAgentUrl(currentAgentUrl) === normalizeAgentUrl(adamAgentUrl)
-            ? null
-            : adamAgentUrl;
+        const currentAgentUrls = [currentAgentUrl, ...(currentAgentAliases || [])].filter(
+            (agentUrl): agentUrl is string_agent_url => Boolean(agentUrl),
+        );
+        const isCurrentAgentAdam = currentAgentUrls.some(
+            (agentUrl) => normalizeAgentUrl(agentUrl) === normalizeAgentUrl(adamAgentUrl),
+        );
+
+        return isCurrentAgentAdam ? null : adamAgentUrl;
     }
 
     throw new ParseError(
@@ -496,7 +503,7 @@ async function resolveParentAgentContext(
     agentSource: string_book,
     context: AgentImportContext,
 ): Promise<ResolvedParentAgentContext> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(agentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(agentSource);
     const hasExplicitFromCommitment = explicitFromContent !== undefined;
     const resolvedParentAgentUrl = await resolveParentAgentUrlFromCommitments(
         agentSource,
@@ -510,14 +517,21 @@ async function resolveParentAgentContext(
         hasExplicitFromCommitment,
         context.adamAgentUrl,
         context.resolutionOptions?.currentAgentUrl,
+        context.resolutionOptions?.currentAgentAliases,
         agentSource,
     );
-    const parentAgentSourceCorpus = parentAgentUrl ? await importAgentCorpus(parentAgentUrl, 'FROM', context) : null;
+    const isCyclicFrom = Boolean(parentAgentUrl && findResolutionCycle(parentAgentUrl, context.resolutionOptions));
+    const effectiveParentAgentUrl = isCyclicFrom ? null : parentAgentUrl;
+    const parentAgentSourceCorpus = effectiveParentAgentUrl
+        ? await importAgentCorpus(effectiveParentAgentUrl, 'FROM', context)
+        : null;
 
     return {
-        parentAgentUrl,
+        // A parent that closes the current lineage has the same runtime effect as `FROM @Null`.
+        parentAgentUrl: effectiveParentAgentUrl,
         parentAgentSourceCorpus,
         fromResolutionIssues,
+        isCyclicFrom,
     };
 }
 
@@ -591,36 +605,18 @@ async function resolveImportCommitmentLine(line: string, context: AgentImportCon
 }
 
 /**
- * Resolves one explicit `FROM ...` line into inherited content or fallback NOTE lines.
+ * Resolves the effective `FROM ...` line into inherited content or fallback NOTE lines.
  *
  * @param line - Current source line.
- * @param agentSource - Full source used for duplicate-`FROM` diagnostics.
- * @param isFromResolved - Whether a previous `FROM ...` line was already handled.
  * @param parentContext - Effective parent state computed earlier in the resolution.
  * @returns Output lines and remaining `FROM` issues.
  */
 function resolveFromCommitmentLine(
     line: string,
-    agentSource: string_book,
-    isFromResolved: boolean,
     parentContext: ResolvedParentAgentContext,
 ): ResolvedFromCommitmentLine {
-    if (isFromResolved) {
-        throw new UnexpectedError(
-            spaceTrim(
-                (block) => `
-                    Multiple \`FROM\` commitments found in agent source:
-
-                    \`\`\`book
-                    ${block(agentSource)}
-                    \`\`\`
-                `,
-            ),
-        );
-    }
-
     if (parentContext.parentAgentUrl === null) {
-        const agentSourceChunks = [line];
+        const agentSourceChunks = [parentContext.isCyclicFrom ? 'FROM @Null' : line];
 
         if (parentContext.fromResolutionIssues.length > 0) {
             appendResolutionIssueNotes(agentSourceChunks, parentContext.fromResolutionIssues);
@@ -654,6 +650,23 @@ function resolveFromCommitmentLine(
     };
 }
 
+/**
+ * Finds the `FROM` lines that a later `FROM` takes precedence over.
+ *
+ * A book is allowed to repeat `FROM`; the last one wins, so every earlier one is dropped instead of being resolved.
+ * The Book editor warns about this while the author is still writing the book.
+ *
+ * @param explicitFromCommitments - Explicit parent declarations found in source order.
+ * @returns Zero-based indexes of every overridden `FROM` line, empty when at most one `FROM` is present.
+ */
+function collectOverriddenFromLineIndexes(
+    explicitFromCommitments: ReadonlyArray<{ readonly lineIndex: number }>,
+): ReadonlySet<number> {
+    return new Set(
+        explicitFromCommitments.slice(0, -1).map((explicitFromCommitment) => explicitFromCommitment.lineIndex),
+    );
+}
+
 /**
  * Rewrites the source body line by line while delegating each branching step to a focused helper.
  *
@@ -669,26 +682,31 @@ async function resolveAgentSourceBuild(
 ): Promise<ResolvedAgentSourceBuild> {
     const agentSourceChunks = spaceTrim(agentSource).split(/\r?\n/);
     const resolvedAgentSourceChunks: Array<string> = [];
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSourceChunks);
+    const effectiveFromCommitment = explicitFromCommitments[explicitFromCommitments.length - 1];
+    const overriddenFromLineIndexes = collectOverriddenFromLineIndexes(explicitFromCommitments);
     let isFromResolved = false;
     let fromResolutionIssues = parentContext.fromResolutionIssues;
     // <- TODO: [🈲] Simple and encapsulated way to split book into commitments
 
-    for (const line of agentSourceChunks) {
+    for (let lineIndex = 0; lineIndex < agentSourceChunks.length; lineIndex++) {
+        const line = agentSourceChunks[lineIndex] || '';
+
+        // Note: A repeated `FROM` is overridden by the last one, so the outdated line is dropped from the resolved source.
+        if (overriddenFromLineIndexes.has(lineIndex)) {
+            continue;
+        }
+
         if (line.trim().startsWith('IMPORT ')) {
             resolvedAgentSourceChunks.push(...(await resolveImportCommitmentLine(line, context)));
             continue;
         }
 
-        if (line.trim().startsWith('FROM ')) {
-            const resolvedFromCommitment = resolveFromCommitmentLine(
-                line,
-                agentSource,
-                isFromResolved,
-                {
-                    ...parentContext,
-                    fromResolutionIssues,
-                },
-            );
+        if (effectiveFromCommitment?.lineIndex === lineIndex) {
+            const resolvedFromCommitment = resolveFromCommitmentLine(line, {
+                ...parentContext,
+                fromResolutionIssues,
+            });
 
             resolvedAgentSourceChunks.push(...resolvedFromCommitment.agentSourceChunks);
             fromResolutionIssues = resolvedFromCommitment.fromResolutionIssues;
@@ -779,15 +797,16 @@ function assertNoResolutionCycle(
     commitmentType: 'FROM' | 'IMPORT',
     options?: ResolveInheritedAgentSourceOptions,
 ): void {
-    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
-    const lineage = createResolutionLineage(options);
-    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+    const resolutionCycle = findResolutionCycle(referenceUrl, options);
 
-    if (cycleStartIndex === -1) {
+    if (!resolutionCycle) {
         return;
     }
 
-    const cycleChain = [...lineage.slice(cycleStartIndex), normalizedReferenceUrl]
+    const cycleChain = [
+        ...resolutionCycle.lineage.slice(resolutionCycle.cycleStartIndex),
+        resolutionCycle.normalizedReferenceUrl,
+    ]
         .map((visitedUrl) => `- \`${visitedUrl}\``)
         .join('\n');
 

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

@@ -107,6 +107,10 @@ export type UserChatTimeout = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;

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

@@ -27,6 +27,10 @@ export type UserChatTimeoutRecord = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -55,6 +59,10 @@ export type UserChatTimeoutRow = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    startsAt: string | null;
+    endsAt: string | null;
+    maxRunCount: number | null;
     queuedAt: string;
     startedAt: string | null;
     completedAt: string | null;
@@ -83,6 +91,10 @@ export type UserChatTimeoutInsert = {
     durationMs: number;
     dueAt: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     queuedAt: string;
     startedAt?: string | null;
     completedAt?: string | null;
@@ -97,15 +109,22 @@ export type UserChatTimeoutInsert = {
 
 /**
  * Input used when persisting one new chat timeout.
+ *
+ * The schedule fields describe the whole life of a planned message, so `durationMs` and `dueAt` are
+ * only needed by a caller that schedules one plain wake-up at a fixed delay.
  */
 export type CreateUserChatTimeoutOptions = {
     id?: string;
     userId: number;
     agentPermanentId: string;
     chatId: string;
-    durationMs: number;
+    durationMs?: number;
     dueAt?: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     message?: string;
     parameters?: UserChatTimeoutParameters;
 };
@@ -130,6 +149,16 @@ export type ListUserChatTimeoutsOptions = {
     onlyActive?: boolean;
 };
 
+/**
+ * Query options for listing the timeouts of every agent on the server.
+ */
+export type ListAllUserChatTimeoutsOptions = {
+    /**
+     * Largest number of rows to return, newest first.
+     */
+    limit: number;
+};
+
 /**
  * Query options for loading one timeout scoped only to user + agent.
  */
@@ -162,10 +191,17 @@ export type ListAgentUserChatTimeoutsOptions = {
 
 /**
  * Mutable fields accepted when editing one agent-scoped timeout.
+ *
+ * Every schedule field that is present is written, so leaving one out keeps it as it is and passing
+ * `null` removes it.
  */
 export type UpdateAgentScopedUserChatTimeoutPatch = {
     dueAt?: string;
     recurrenceIntervalMs?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
     message?: string | null;
     parameters?: UserChatTimeoutParameters;
     pausedAt?: string | null;

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

@@ -1,6 +1,7 @@
+import { setAgentScopedUserChatTimeoutPausedState } from './setAgentScopedUserChatTimeoutPausedState';
 import type { UserChatTimeoutStatus, UserChatTimeoutRecord } from './UserChatTimeoutRecord';
-import { listAgentUserChatTimeouts, updateAgentScopedUserChatTimeout } from './userChatTimeoutStore';
-import { cancelScheduledUserChatTimeout, notifyUserChatTimeoutScheduleChanged } from './userChatTimeoutWorker';
+import { listAgentUserChatTimeouts } from './userChatTimeoutStore';
+import { cancelScheduledUserChatTimeout } from './userChatTimeoutWorker';
 
 /**
  * Number of timeout rows loaded per page while collecting bulk-mutation targets.
@@ -68,22 +69,18 @@ export async function pauseAllActiveAgentScopedUserChatTimeouts(options: {
         statuses: ['QUEUED'],
         paused: false,
     });
-    const pausedAtIso = new Date().toISOString();
     const pausedTimeoutIds: Array<string> = [];
 
     for (const timeout of collectedTimeouts.timeouts) {
-        const updatedTimeout = await updateAgentScopedUserChatTimeout({
+        const pauseResult = await setAgentScopedUserChatTimeoutPausedState({
             userId: options.userId,
             agentPermanentId: options.agentPermanentId,
             timeoutId: timeout.timeoutId,
-            patch: {
-                pausedAt: pausedAtIso,
-            },
+            isPaused: true,
         });
 
-        if (updatedTimeout && updatedTimeout.pausedAt) {
-            notifyUserChatTimeoutScheduleChanged(updatedTimeout);
-            pausedTimeoutIds.push(updatedTimeout.timeoutId);
+        if (pauseResult.isApplied) {
+            pausedTimeoutIds.push(pauseResult.plannedMessage.timeoutId);
         }
     }
 
@@ -111,18 +108,15 @@ export async function resumeAllPausedAgentScopedUserChatTimeouts(options: {
     const resumedTimeoutIds: Array<string> = [];
 
     for (const timeout of collectedTimeouts.timeouts) {
-        const updatedTimeout = await updateAgentScopedUserChatTimeout({
+        const resumeResult = await setAgentScopedUserChatTimeoutPausedState({
             userId: options.userId,
             agentPermanentId: options.agentPermanentId,
             timeoutId: timeout.timeoutId,
-            patch: {
-                pausedAt: null,
-            },
+            isPaused: false,
         });
 
-        if (updatedTimeout && !updatedTimeout.pausedAt) {
-            notifyUserChatTimeoutScheduleChanged(updatedTimeout);
-            resumedTimeoutIds.push(updatedTimeout.timeoutId);
+        if (resumeResult.isApplied) {
+            resumedTimeoutIds.push(resumeResult.plannedMessage.timeoutId);
         }
     }
 

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

@@ -1,30 +1,54 @@
 import { spaceTrim } from 'spacetrim';
-import { formatTimeoutDurationHuman } from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import {
+    describeAgentPlannedMessageSchedule,
+    type AgentPlannedMessageScheduleDescription,
+} from '../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
 
 /**
  * Builds the synthetic user-like message injected when a timeout elapses.
  *
- * A repeating planned message stays armed after every firing, so its wake-up says so: the agent
- * only has to act on the message itself, not to plan the same wake-up again.
+ * A planned message carries its whole schedule into its own wake-up, so the agent immediately knows
+ * whether this was its last run and does not have to plan anything again just to keep the plan alive.
  *
  * @private internal utility of userChatTimeout
  */
-export function createTimeoutWakeUpMessage(options: {
-    readonly timeoutId: string;
-    readonly durationMs: number;
-    readonly intervalMs?: number | null;
-    readonly message?: string | null;
-}): string {
+export function createTimeoutWakeUpMessage(
+    options: AgentPlannedMessageScheduleDescription & {
+        readonly timeoutId: string;
+        readonly durationMs: number;
+        readonly message?: string | null;
+    },
+): string {
     const message = options.message?.trim() || '';
-    const headline = options.intervalMs
-        ? `⏱️ Planned message elapsed, repeating every ${formatTimeoutDurationHuman(options.intervalMs)}.`
-        : `⏱️ Timeout elapsed after ${options.durationMs}ms.`;
 
     return spaceTrim(
         (block) => `
-            ${headline}
+            ${createTimeoutWakeUpHeadline(options)}
             timeoutId: ${options.timeoutId}
             ${message ? block(message) : ''}
         `,
     );
 }
+
+/**
+ * Builds the first line of one wake-up, telling the agent what woke it and where in its plan it is.
+ *
+ * @param options - Schedule of the planned message together with the plain timeout duration.
+ * @returns Headline of the wake-up message.
+ *
+ * @private internal utility of `createTimeoutWakeUpMessage`
+ */
+function createTimeoutWakeUpHeadline(
+    options: AgentPlannedMessageScheduleDescription & { readonly durationMs: number },
+): string {
+    if (options.intervalMs || options.cronExpression) {
+        // Note: The next wake-up is resolved only after this one is queued, so the schedule is described without it
+        return `⏱️ Planned message elapsed, ${describeAgentPlannedMessageSchedule({ ...options, dueAt: null })}.`;
+    }
+
+    if (options.maxRunCount || options.startsAt) {
+        return '⏱️ Planned message elapsed, this was its only wake-up.';
+    }
+
+    return `⏱️ Timeout elapsed after ${options.durationMs}ms.`;
+}

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