@promptbook/cli 0.114.0-3 → 0.114.0-30

package/apps/agents-server/src/utils/userChat/persistFrozenUserChat.ts

@@ -3,6 +3,7 @@ import type { UserChatRecord } from './UserChatRecord';
 import { createUserChat } from './createUserChat';
 import { updateUserChatMessages } from './updateUserChatMessages';
 import { isFrozenUserChatSource, type UserChatSource } from './UserChatSource';
+import { isUserChatNotFoundScopeError } from './UserChatScopeError';
 
 /**
  * Input payload for persisting one frozen external chat snapshot.
@@ -24,12 +25,26 @@ export async function persistFrozenUserChat(options: PersistFrozenUserChatOption
     }
 
     if (options.chatId) {
-        return updateUserChatMessages({
-            userId: options.userId,
-            agentPermanentId: options.agentPermanentId,
-            chatId: options.chatId,
-            messages: options.messages,
-        });
+        try {
+            return await updateUserChatMessages({
+                userId: options.userId,
+                agentPermanentId: options.agentPermanentId,
+                chatId: options.chatId,
+                messages: options.messages,
+            });
+        } catch (error) {
+            if (!isUserChatNotFoundScopeError(error)) {
+                throw error;
+            }
+
+            return createUserChat({
+                userId: options.userId,
+                agentPermanentId: options.agentPermanentId,
+                source: options.source,
+                chatId: options.chatId,
+                messages: options.messages,
+            });
+        }
     }
 
     return createUserChat({

package/apps/agents-server/src/utils/userChat/persistUserChatJobTerminalState.ts

@@ -28,6 +28,10 @@ export async function persistUserChatJobTerminalState(options: {
     provider?: string | null;
     failureReason?: string | null;
     failureDetails?: string | null;
+    /**
+     * Actual time at which an out-of-process runner finished this assistant message.
+     */
+    executedAt?: NonNullable<ChatMessage['createdAt']>;
     generationDurationMs?: number;
 }): Promise<void> {
     let updatedChat: Awaited<ReturnType<typeof updateUserChatAssistantMessage>> | null = null;
@@ -47,6 +51,7 @@ export async function persistUserChatJobTerminalState(options: {
                 ongoingToolCalls: undefined,
                 toolCalls: options.toolCalls ?? message.toolCalls,
                 completedToolCalls: options.toolCalls ?? message.completedToolCalls,
+                createdAt: options.executedAt ?? message.createdAt,
                 generationDurationMs: options.generationDurationMs ?? message.generationDurationMs,
                 progressCard: undefined,
                 availableTools: options.availableTools ?? message.availableTools,

package/apps/agents-server/src/utils/userChat/resolveUserChatWorkerInternalToken.ts

@@ -13,7 +13,7 @@ import { EnvironmentMismatchError } from '../../../../../src/errors/EnvironmentM
 let resolvedUserChatWorkerInternalToken: string | null = null;
 
 /**
- * Resolves the shared internal token used to protect background worker routes.
+ * Resolves the shared internal token used to protect managed-agent and background worker routes.
  *
  * In production, `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN` must be configured
  * explicitly — falling back to any shared credential (in particular
@@ -44,11 +44,12 @@ export function resolveUserChatWorkerInternalToken(): string {
             spaceTrim(`
                 Missing required \`PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN\` environment variable in production.
 
-                The Agents Server protects its internal worker routes
+                The Agents Server protects its internal managed-agent and worker routes
                 (\`/api/internal/user-chat-jobs/run\`,
                 \`/api/internal/user-chat-timeouts/run\`,
-                \`/api/internal/agent-runner-limits\`, and
-                \`/api/internal/agent-project-runtimes\`) with this shared token.
+                \`/api/internal/agent-runner-limits\`,
+                \`/api/internal/agent-project-runtimes\`, and
+                \`/api/internal/agent-goal-chat-planned-messages\`) with this shared token.
                 Reusing \`ADMIN_PASSWORD\`, \`SUPABASE_SERVICE_ROLE_KEY\`, or a
                 hardcoded fallback would let anyone who learns that value drive
                 background jobs at will.

package/apps/agents-server/src/utils/userChat/runImmediateUserChatAnswer.ts

@@ -9,7 +9,7 @@ import type { ChatMessage, ChatPrompt } from '@promptbook-local/types';
 import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
 import type { ChatPromptResult } from '../../../../../src/execution/PromptResult';
 import { createImmediateUserChatAnswerModelRequirements } from './createImmediateUserChatAnswerModelRequirements';
-import { getUserChat } from './getUserChat';
+import { getUserChatForJobRunner } from './getUserChatForJobRunner';
 import { getUserChatJobById } from './getUserChatJobById';
 import { mutateUserChat } from './mutateUserChat';
 import type { UserChatJobParameters, UserChatJobRecord } from './UserChatJobRecord';
@@ -109,11 +109,7 @@ async function resolveImmediateUserChatAnswerContext(
         return null;
     }
 
-    const chat = await getUserChat({
-        userId: job.userId,
-        agentPermanentId: job.agentPermanentId,
-        chatId: job.chatId,
-    });
+    const chat = await getUserChatForJobRunner(job);
 
     if (!chat) {
         return null;

package/apps/agents-server/src/utils/userChat/runUserChatJob.ts

@@ -17,7 +17,7 @@ import {
     DEFAULT_USER_CHAT_JOB_HEARTBEAT_MAX_CONSECUTIVE_FAILURES,
 } from './createUserChatJobHeartbeatController';
 import { finalizeUserChatJob } from './finalizeUserChatJob';
-import { getUserChat } from './getUserChat';
+import { getUserChatForJobRunner } from './getUserChatForJobRunner';
 import { heartbeatUserChatJob } from './heartbeatUserChatJob';
 import { persistUserChatJobTerminalState } from './persistUserChatJobTerminalState';
 import { persistUserChatJobProgressCard } from './persistUserChatJobProgressCard';
@@ -159,11 +159,7 @@ function createRunUserChatJobProgressReporter(
  */
 async function resolveRunUserChatJobStartContext(job: UserChatJobRecord): Promise<RunUserChatJobStartContext | null> {
     const [chat, userRow] = await Promise.all([
-        getUserChat({
-            userId: job.userId,
-            agentPermanentId: job.agentPermanentId,
-            chatId: job.chatId,
-        }),
+        getUserChatForJobRunner(job),
         getUserById(job.userId),
     ]);
 

package/apps/agents-server/src/utils/userChat/teamMemberUserChatContext.ts

@@ -0,0 +1,63 @@
+import type { ChatMessage } from '@promptbook-local/types';
+
+/**
+ * JSON property stored on the first message of a frozen TEAM conversation.
+ *
+ * A message-level property keeps the relation backwards-compatible without changing the UserChat table.
+ */
+const TEAM_MEMBER_USER_CHAT_CONTEXT_KEY = '__promptbookTeamMemberChat';
+
+/**
+ * Primary chat information attached to a frozen teammate conversation.
+ */
+export type TeamMemberUserChatContext = {
+    readonly version: 1;
+    readonly primaryAgentPermanentId: string;
+    readonly primaryAgentName: string;
+    readonly primaryChatId: string;
+};
+
+/**
+ * Adds the primary-chat relation to the first message of a frozen teammate transcript.
+ */
+export function attachTeamMemberUserChatContext(
+    messages: ReadonlyArray<ChatMessage>,
+    context: TeamMemberUserChatContext,
+): Array<ChatMessage> {
+    const firstMessage = messages[0];
+    if (!firstMessage) {
+        return [...messages];
+    }
+
+    return [
+        {
+            ...firstMessage,
+            [TEAM_MEMBER_USER_CHAT_CONTEXT_KEY]: context,
+        } as ChatMessage,
+        ...messages.slice(1),
+    ];
+}
+
+/**
+ * Reads the optional primary-chat relation from a frozen teammate transcript.
+ */
+export function getTeamMemberUserChatContext(messages: ReadonlyArray<ChatMessage>): TeamMemberUserChatContext | null {
+    const firstMessage = messages[0] as (ChatMessage & Record<string, unknown>) | undefined;
+    const value = firstMessage?.[TEAM_MEMBER_USER_CHAT_CONTEXT_KEY];
+
+    return isTeamMemberUserChatContext(value) ? value : null;
+}
+
+/**
+ * Validates the compact context stored in untrusted persisted message JSON.
+ */
+function isTeamMemberUserChatContext(value: unknown): value is TeamMemberUserChatContext {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            (value as TeamMemberUserChatContext).version === 1 &&
+            typeof (value as TeamMemberUserChatContext).primaryAgentPermanentId === 'string' &&
+            typeof (value as TeamMemberUserChatContext).primaryAgentName === 'string' &&
+            typeof (value as TeamMemberUserChatContext).primaryChatId === 'string',
+    );
+}

package/apps/agents-server/src/utils/userChat/userChatJobRunReport.ts

@@ -1,4 +1,5 @@
 import type { Json } from '@/src/database/schema';
+import type { ChatMessage } from '@promptbook-local/types';
 import {
     normalizeAgentMessageRunReport,
     type AgentMessageRunReport,
@@ -42,6 +43,35 @@ export function withUserChatJobRunReport(
     };
 }
 
+/**
+ * Resolves display-ready execution timing from one runner-produced message report.
+ *
+ * The runner's timestamps describe only active harness work, unlike durable job timestamps which also include time
+ * waiting for the out-of-process runner to pick up a queued message.
+ *
+ * @returns The completed message timestamp and actual execution duration, or `null` for older reports without timing.
+ */
+export function resolveUserChatJobExecutionTiming(report: AgentMessageRunReport | null): {
+    readonly executedAt: NonNullable<ChatMessage['createdAt']>;
+    readonly generationDurationMs: number;
+} | null {
+    const executionTiming = report?.executionTiming;
+    if (!executionTiming) {
+        return null;
+    }
+
+    const startedAtMilliseconds = Date.parse(executionTiming.startedAt);
+    const finishedAtMilliseconds = Date.parse(executionTiming.finishedAt);
+    if (!Number.isFinite(startedAtMilliseconds) || !Number.isFinite(finishedAtMilliseconds)) {
+        return null;
+    }
+
+    return {
+        executedAt: executionTiming.finishedAt as NonNullable<ChatMessage['createdAt']>,
+        generationDurationMs: Math.max(0, finishedAtMilliseconds - startedAtMilliseconds),
+    };
+}
+
 /**
  * Persists one runner-produced run report into the job parameters so task details can show it.
  */

package/apps/agents-server/src/utils/userChat/userChatMessageLifecycle.ts

@@ -20,13 +20,18 @@ export function createQueuedUserChatUserMessage(options: {
     messageId: string;
     clientMessageId: string;
     content: string;
+    /**
+     * Sender persisted for the input turn. Agent-owned goal-chat wake-ups use `AGENT` because
+     * no human authored them, while ordinary durable turns keep the default `USER` sender.
+     */
+    sender?: 'USER' | 'AGENT';
     attachments?: ChatMessage['attachments'];
     replyingTo?: ChatMessage['replyingTo'];
     createdAt: NonNullable<ChatMessage['createdAt']>;
 }): ChatMessage {
     return {
         id: options.messageId,
-        sender: 'USER',
+        sender: options.sender || 'USER',
         content: options.content,
         attachments: options.attachments,
         replyingTo: options.replyingTo,

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

@@ -16,7 +16,11 @@ export { getUserChatJobByClientMessageId } from './userChat/getUserChatJobByClie
 export { heartbeatUserChatJob } from './userChat/heartbeatUserChatJob';
 export { isUserChatViewOnly } from './userChat/isUserChatViewOnly';
 export { listExpiredRunningUserChatJobs } from './userChat/listExpiredRunningUserChatJobs';
-export { listUserChats, listUserChatSummarySeeds } from './userChat/listUserChats';
+export {
+    createUserChatSummarySeedFromChatRecord,
+    listUserChats,
+    listUserChatSummarySeeds,
+} from './userChat/listUserChats';
 export { listUserChatJobActivityCounts, listUserChatJobs } from './userChat/listUserChatJobs';
 export { mutateUserChat } from './userChat/mutateUserChat';
 export { persistUserChatJobTerminalState } from './userChat/persistUserChatJobTerminalState';

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

@@ -4,7 +4,7 @@ import type { UserChatTimeout } from '../userChatClient';
 import { requestUserChatApi } from './requestUserChatApi';
 
 /**
- * Cancels one durable timeout in the agent-wide timeout manager.
+ * Cancels one planned message of the agent from its goal chat.
  *
  * @private shared helper for the Agents Server browser client
  */
@@ -14,6 +14,6 @@ export async function cancelAgentUserTimeout(agentName: string, timeoutId: strin
         {
             method: 'DELETE',
         },
-        'Failed to cancel agent timeout.',
+        'Failed to cancel the planned message.',
     );
 }

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

@@ -4,7 +4,7 @@ import type { AgentUserTimeoutListResponse } from '../userChatClient';
 import { requestUserChatApi } from './requestUserChatApi';
 
 /**
- * Loads all durable timeouts for one user+agent across chats.
+ * Loads every planned message of one agent, as listed in its goal chat.
  *
  * @private shared helper for the Agents Server browser client
  */
@@ -15,6 +15,6 @@ export async function fetchAgentUserTimeouts(agentName: string): Promise<AgentUs
             method: 'GET',
             cache: 'no-store',
         },
-        'Failed to load agent timeouts.',
+        'Failed to load planned messages.',
     );
 }

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

@@ -12,12 +12,10 @@ export { fetchAgentUserTimeouts } from './userChatClient/fetchAgentUserTimeouts'
 export { fetchUserChat } from './userChatClient/fetchUserChat';
 export { fetchUserChats } from './userChatClient/fetchUserChats';
 export { removeUserChat } from './userChatClient/removeUserChat';
-export { runAgentUserTimeoutBulkAction } from './userChatClient/runAgentUserTimeoutBulkAction';
 export { saveUserChatDraft } from './userChatClient/saveUserChatDraft';
 export { saveUserChatMessages } from './userChatClient/saveUserChatMessages';
 export { sendUserChatMessage } from './userChatClient/sendUserChatMessage';
 export { streamUserChat } from './userChatClient/streamUserChat';
-export { updateAgentUserTimeout } from './userChatClient/updateAgentUserTimeout';
 export { UserChatApiError } from './userChatClient/UserChatApiError';
 
 /**
@@ -39,12 +37,21 @@ export type UserChatSummary = {
     updatedAt: string;
     lastMessageAt: string | null;
     source: UserChatSource;
+    /**
+     * Database user id owning the chat, used to link a super-admin to its owner.
+     */
+    userId?: number;
     isReadOnly: boolean;
     /**
      * True when the chat belongs to a different user than the current viewer
      * (visible only to admins/super-admins browsing external chats).
      */
     isExternalUserChat?: boolean;
+    /**
+     * True for the singleton goal chat the agent keeps with itself, which is pinned above
+     * every other chat and rendered with its own icon.
+     */
+    isAgentGoalChat?: boolean;
     messagesCount: number;
     title: string;
     preview: string;
@@ -100,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;
@@ -134,35 +145,6 @@ export type AgentUserTimeoutListResponse = {
     generatedAt: string;
 };
 
-/**
- * Editable timeout fields accepted by the agent-wide timeout update endpoint.
- */
-export type AgentUserTimeoutUpdatePayload = {
-    dueAt?: string;
-    recurrenceIntervalMs?: number | null;
-    message?: string | null;
-    parameters?: Record<string, unknown>;
-    paused?: boolean;
-    extendByMs?: number;
-};
-
-/**
- * Supported bulk timeout actions in the agent-wide timeout manager.
- */
-export type AgentUserTimeoutBulkAction = 'cancel_all_active' | 'pause_all_active' | 'resume_all_paused';
-
-/**
- * API payload returned after one bulk timeout action.
- */
-export type AgentUserTimeoutBulkActionResponse = {
-    action: AgentUserTimeoutBulkAction;
-    matchedCount: number;
-    updatedCount: number;
-    timeoutIds: Array<string>;
-    hasMore: boolean;
-    generatedAt: string;
-};
-
 /**
  * API payload for list endpoint.
  */

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,11 +149,25 @@ 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.
  */
 export type GetAgentScopedUserChatTimeoutOptions = {
-    userId: number;
+    /**
+     * Owning user, or `undefined` to span every user of the agent
+     * (used by the agent goal chat, which plans on behalf of the agent itself).
+     */
+    userId?: number;
     agentPermanentId: string;
     timeoutId: string;
 };
@@ -143,7 +176,11 @@ export type GetAgentScopedUserChatTimeoutOptions = {
  * Query options for listing all timeouts owned by one user+agent across chats.
  */
 export type ListAgentUserChatTimeoutsOptions = {
-    userId: number;
+    /**
+     * Owning user, or `undefined` to span every user of the agent
+     * (used by the agent goal chat, which plans on behalf of the agent itself).
+     */
+    userId?: number;
     agentPermanentId: string;
     statuses?: ReadonlyArray<UserChatTimeoutStatus>;
     includePaused?: boolean;
@@ -154,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,22 +1,54 @@
 import { spaceTrim } from 'spacetrim';
+import {
+    describeAgentPlannedMessageSchedule,
+    type AgentPlannedMessageScheduleDescription,
+} from '../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
 
 /**
  * Builds the synthetic user-like message injected when a timeout elapses.
  *
+ * 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 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() || '';
 
     return spaceTrim(
         (block) => `
-            ⏱️ Timeout elapsed after ${options.durationMs}ms.
+            ${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.`;
+}