@promptbook/cli 0.114.0-11 → 0.114.0-13

package/apps/agents-server/src/utils/localChatRunner/applyLocalAgentPlannedMessageCommands.ts

@@ -0,0 +1,212 @@
+import { readFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { serializeError } from '@promptbook-local/utils';
+import {
+    createAgentPlannedMessagesSidecarPath,
+    parseAgentPlannedMessagesSidecar,
+    type AgentPlannedMessageCommand,
+} from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
+import {
+    AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    type CancelAgentGoalChatPlannedMessageResult,
+    type SetAgentGoalChatPlannedMessageResult,
+} from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Planned-message operations used while applying one sidecar.
+ */
+export type LocalAgentPlannedMessageActions = Pick<typeof AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS, 'set' | 'cancel'>;
+
+/**
+ * One planned-message command that was applied together with its result.
+ *
+ * The command carries what the agent asked for (for example the requested delay) and the result
+ * carries what really happened, so the chat can show the wake-up below the message that planned it.
+ */
+export type AppliedAgentPlannedMessageCommand = {
+    readonly command: AgentPlannedMessageCommand;
+    readonly result: SetAgentGoalChatPlannedMessageResult | CancelAgentGoalChatPlannedMessageResult;
+};
+
+/**
+ * Applies every planned-message command a coding harness wrote while answering one message.
+ *
+ * The sidecar is consumed exactly once: it is removed afterwards so a replayed worker tick can never
+ * schedule the very same wake-up twice.
+ *
+ * @param options - Answered job, its agent folder path, and the local runner metadata of the message.
+ * @returns Planned-message commands that were applied successfully, in sidecar order.
+ */
+export async function applyLocalAgentPlannedMessageCommands(options: {
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId' | 'agentPermanentId'>;
+    readonly agentDirectoryPath: string;
+    readonly metadata: LocalUserChatJobMetadata;
+    readonly actions?: LocalAgentPlannedMessageActions;
+}): Promise<ReadonlyArray<AppliedAgentPlannedMessageCommand>> {
+    const sidecarPath = resolveLocalAgentPlannedMessagesSidecarPath(options.agentDirectoryPath, options.metadata);
+    const sidecarContent = await readOptionalTextFile(sidecarPath);
+
+    await removeLocalAgentPlannedMessagesSidecar(options.agentDirectoryPath, options.metadata);
+
+    if (sidecarContent === null) {
+        return [];
+    }
+
+    const sidecar = parseAgentPlannedMessagesSidecar(sidecarContent);
+
+    if (!sidecar) {
+        console.warn('[local-chat-runner] planned_messages_sidecar_unreadable', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+        });
+        return [];
+    }
+
+    const actions = options.actions || AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS;
+    const appliedCommands: Array<AppliedAgentPlannedMessageCommand> = [];
+
+    for (const command of sidecar.commands) {
+        const result = await applyLocalAgentPlannedMessageCommand({
+            command,
+            actions,
+            agentPermanentId: options.job.agentPermanentId,
+            job: options.job,
+        });
+
+        if (result) {
+            appliedCommands.push({ command, result });
+        }
+    }
+
+    return appliedCommands;
+}
+
+/**
+ * Removes the planned-message sidecar of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ */
+export async function removeLocalAgentPlannedMessagesSidecar(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): Promise<void> {
+    await rm(resolveLocalAgentPlannedMessagesSidecarPath(agentDirectoryPath, metadata), { force: true }).catch(
+        () => undefined,
+    );
+}
+
+/**
+ * Dispatches one planned-message command through the shared planned-message actions.
+ *
+ * One rejected command never blocks the remaining ones, because the agent already answered and the
+ * harness owns this sidecar.
+ *
+ * @param options - Command, actions, and the agent whose goal chat owns the planned message.
+ * @returns Result of the applied command, or `null` when it was rejected.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+async function applyLocalAgentPlannedMessageCommand(options: {
+    readonly command: AgentPlannedMessageCommand;
+    readonly actions: LocalAgentPlannedMessageActions;
+    readonly agentPermanentId: string;
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId'>;
+}): Promise<AppliedAgentPlannedMessageCommand['result'] | null> {
+    try {
+        if (options.command.action === 'set') {
+            const plannedMessage = await options.actions.set({
+                agentPermanentId: options.agentPermanentId,
+                milliseconds: options.command.milliseconds,
+                message: options.command.message,
+            });
+
+            console.info('[local-chat-runner]', 'planned_message_set', {
+                chatId: options.job.chatId,
+                jobId: options.job.id,
+                timeoutId: plannedMessage.timeoutId,
+                dueAt: plannedMessage.dueAt,
+            });
+
+            return plannedMessage;
+        }
+
+        const cancelledPlannedMessage = await options.actions.cancel({
+            agentPermanentId: options.agentPermanentId,
+            timeoutId: options.command.timeoutId,
+        });
+
+        console.info('[local-chat-runner]', 'planned_message_cancel', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            timeoutId: cancelledPlannedMessage.timeoutId,
+            status: cancelledPlannedMessage.status,
+        });
+
+        return cancelledPlannedMessage.status === 'cancelled' ? cancelledPlannedMessage : null;
+    } catch (error) {
+        console.error('[local-chat-runner]', 'planned_message_command_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            action: options.command.action,
+            error: serializeError(error as Error),
+        });
+
+        return null;
+    }
+}
+
+/**
+ * Resolves the absolute planned-message sidecar path of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ * @returns Absolute sidecar path.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function resolveLocalAgentPlannedMessagesSidecarPath(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): string {
+    return join(agentDirectoryPath, createAgentPlannedMessagesSidecarPath(metadata.fileName));
+}
+
+/**
+ * Reads one text file and treats a missing planned-message sidecar as absent.
+ *
+ * @param path - Absolute sidecar path.
+ * @returns File content, or `null` when the sidecar does not exist.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+async function readOptionalTextFile(path: string): Promise<string | null> {
+    try {
+        return await readFile(path, 'utf-8');
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Returns true when one filesystem error indicates a missing path.
+ *
+ * @param error - Caught filesystem failure.
+ * @returns `true` for missing-path errors.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function isFileNotFoundError(error: unknown): boolean {
+    return Boolean(
+        error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            ((error as { code?: string }).code === 'ENOENT' || (error as { code?: string }).code === 'ENOTDIR'),
+    );
+}

package/apps/agents-server/src/utils/localChatRunner/prepareLocalAgentPlannedMessagesSidecar.ts

@@ -0,0 +1,66 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import {
+    createAgentPlannedMessagesSidecarContent,
+    createAgentPlannedMessagesSidecarPath,
+    type AgentPlannedMessageSnapshot,
+    type AgentPlannedMessagesSidecar,
+} from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
+import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalAgentFolder } from './ensureLocalAgentFolder';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Writes the planned-message sidecar a coding harness uses to see and change its future wake-ups.
+ *
+ * The sidecar is the only planning channel of a locally executed turn: the harness never has to reach
+ * the Agents Server over the network, and a wake-up exists only when it was actually requested here.
+ * Planned messages repeat on their own, so an empty `commands` array keeps the current plan intact.
+ *
+ * @param options - Answered job, its agent folder, and the local runner metadata of the queued message.
+ */
+export async function prepareLocalAgentPlannedMessagesSidecar(options: {
+    readonly job: Pick<UserChatJobRecord, 'agentPermanentId'>;
+    readonly agentFolder: LocalAgentFolder;
+    readonly metadata: LocalUserChatJobMetadata;
+}): Promise<void> {
+    const sidecarPath = join(
+        options.agentFolder.directoryPath,
+        createAgentPlannedMessagesSidecarPath(options.metadata.fileName),
+    );
+    const plannedMessages = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.list({
+        agentPermanentId: options.job.agentPermanentId,
+    });
+    const sidecar: AgentPlannedMessagesSidecar = {
+        version: 1,
+        agentPermanentId: options.job.agentPermanentId,
+        currentPlannedMessages: plannedMessages.items.map(createLocalAgentPlannedMessageSnapshot),
+        commands: [],
+    };
+
+    await mkdir(dirname(sidecarPath), { recursive: true });
+    await writeFile(sidecarPath, createAgentPlannedMessagesSidecarContent(sidecar), 'utf-8');
+}
+
+/**
+ * Reduces one stored planned message to the fields a coding harness needs.
+ *
+ * @param plannedMessage - Planned message returned by the shared planned-message actions.
+ * @returns Snapshot written into the sidecar.
+ *
+ * @private function of `prepareLocalAgentPlannedMessagesSidecar`
+ */
+function createLocalAgentPlannedMessageSnapshot(plannedMessage: {
+    readonly timeoutId: string;
+    readonly dueAt: string;
+    readonly message: string | null;
+    readonly intervalMs: number | null;
+}): AgentPlannedMessageSnapshot {
+    return {
+        timeoutId: plannedMessage.timeoutId,
+        dueAt: plannedMessage.dueAt,
+        message: plannedMessage.message,
+        intervalMs: plannedMessage.intervalMs,
+    };
+}

package/apps/agents-server/src/utils/localChatRunner/processLocalUserChatJob.ts

@@ -1,11 +1,14 @@
 import type { Json } from '@/src/database/schema';
+import type { ToolCall } from '@promptbook-local/types';
 import { mkdir, readFile, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { parseAgentSource } from '../../../../../src/book-2.0/agent-source/parseAgentSource';
 import {
     buildAgentMessageRunReportPath,
     parseAgentMessageRunReport,
+    type AgentMessageRunReport,
 } from '../../../../../src/book-3.0/AgentMessageRunReport';
+import { createAnsweredMessageChipToolCalls } from '../chatMessageChips/createAnsweredMessageChipToolCalls';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
 import { finalizeUserChatJob } from '../userChat/finalizeUserChatJob';
@@ -14,6 +17,7 @@ import { getUserChatJobById } from '../userChat/getUserChatJobById';
 import { persistUserChatJobTerminalState } from '../userChat/persistUserChatJobTerminalState';
 import { provideUserChatJobTable } from '../userChat/provideUserChatJobTable';
 import { updateUserChatAssistantMessage } from '../userChat/updateUserChatAssistantMessage';
+import { resolveUserChatJobExecutionTiming } from '../userChat/userChatJobRunReport';
 import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
 import type { UserChatJobRow } from '../userChat/UserChatJobRow';
 import { createUserChatRunnerThreadMessages } from '../userChat/userChatMessageLifecycle';
@@ -32,6 +36,12 @@ import {
     parseLocalChatFinishedMessageBook,
 } from './localChatMessageBook';
 import { LOCAL_USER_CHAT_JOB_ANSWER_TIMEOUT_MS, LOCAL_USER_CHAT_JOB_PROVIDER } from './localChatRunnerConstants';
+import {
+    applyLocalAgentPlannedMessageCommands,
+    removeLocalAgentPlannedMessagesSidecar,
+    type AppliedAgentPlannedMessageCommand,
+} from './applyLocalAgentPlannedMessageCommands';
+import { prepareLocalAgentPlannedMessagesSidecar } from './prepareLocalAgentPlannedMessagesSidecar';
 import {
     ensureLocalAgentFolder,
     loadLocalAgentSourceSnapshot,
@@ -191,6 +201,7 @@ async function enqueueLocalUserChatJobWithinTerminalCapture(
         metadata,
         primaryAgentName: agentSourceSnapshot.agentName,
     });
+    await prepareLocalAgentPlannedMessagesSidecarIfPossible({ job, agentFolder, metadata });
     await mkdir(join(agentFolder.directoryPath, 'messages', 'queued'), { recursive: true });
     await writeFile(queuedMessagePath, createLocalChatQueuedMessageBook({ messages: threadMessages }), 'utf-8');
 
@@ -228,6 +239,22 @@ async function prepareLocalTeamConversationWorkspaceIfPossible(
     }
 }
 
+/**
+ * Prepares the planned-message sidecar without preventing an answer when planned messages cannot be read.
+ */
+async function prepareLocalAgentPlannedMessagesSidecarIfPossible(
+    options: Parameters<typeof prepareLocalAgentPlannedMessagesSidecar>[0],
+): Promise<void> {
+    try {
+        await prepareLocalAgentPlannedMessagesSidecar(options);
+    } catch (error) {
+        console.warn('[local-chat-runner] planned_messages_sidecar_prepare_failed', {
+            agentPermanentId: options.job.agentPermanentId,
+            error,
+        });
+    }
+}
+
 /**
  * Synchronizes one already queued local job with message-folder output.
  */
@@ -245,7 +272,15 @@ async function synchronizeLocalUserChatJob(
         });
 
         if (content) {
-            await persistLocalUserChatJobRunReportIfPresent(job, agentDirectoryPath, metadata);
+            const runReport = await persistLocalUserChatJobRunReportIfPresent(job, agentDirectoryPath, metadata);
+            const executionTiming = resolveUserChatJobExecutionTiming(runReport);
+            // Note: Planned messages are applied before the answer becomes terminal, so a wake-up the
+            //       agent announced in its answer is already stored when the answer becomes visible.
+            const appliedPlannedMessageCommands = await applyLocalAgentPlannedMessageCommandsIfPossible({
+                job,
+                agentDirectoryPath,
+                metadata,
+            });
             const teamConversations = await parseFinishedLocalTeamConversations({
                 agentDirectoryPath,
                 metadata,
@@ -255,13 +290,20 @@ async function synchronizeLocalUserChatJob(
                 job,
                 conversations: teamConversations,
             });
+            const chipToolCalls = await createAnsweredMessageChipToolCallsIfPossible({
+                job,
+                appliedPlannedMessageCommands,
+                touchedProjectNames: runReport?.touchedProjectNames || [],
+            });
+            const toolCalls = [...teamToolCalls, ...chipToolCalls];
             await persistUserChatJobTerminalState({
                 job,
                 status: 'COMPLETED',
                 provider: LOCAL_USER_CHAT_JOB_PROVIDER,
                 content,
-                toolCalls: teamToolCalls.length > 0 ? teamToolCalls : undefined,
-                generationDurationMs: resolveLocalUserChatJobDurationMs(metadata.queuedAt),
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                executedAt: executionTiming?.executedAt,
+                generationDurationMs: executionTiming?.generationDurationMs,
             });
             return { didMutate: true, outcome: 'completed' };
         }
@@ -278,26 +320,26 @@ async function synchronizeLocalUserChatJob(
             return { didMutate: false, outcome: 'waiting' };
         }
 
+        await removeLocalAgentPlannedMessagesSidecar(agentDirectoryPath, metadata);
         await persistUserChatJobTerminalState({
             job,
             status: 'FAILED',
             provider: LOCAL_USER_CHAT_JOB_PROVIDER,
             failureReason,
             failureDetails: createLocalUserChatJobFailureDetails(job, failureReason, 'localRunnerFailedFile'),
-            generationDurationMs: resolveLocalUserChatJobDurationMs(metadata.queuedAt),
         });
         return { didMutate: true, outcome: 'failed' };
     }
 
     if (isLocalUserChatJobTimedOut(metadata) && job.status !== 'FAILED') {
         const failureReason = 'Local agent runner did not finish the queued message within 30 minutes.';
+        await removeLocalAgentPlannedMessagesSidecar(agentDirectoryPath, metadata);
         await persistUserChatJobTerminalState({
             job,
             status: 'FAILED',
             provider: LOCAL_USER_CHAT_JOB_PROVIDER,
             failureReason,
             failureDetails: createLocalUserChatJobFailureDetails(job, failureReason, 'localRunnerTimeout'),
-            generationDurationMs: resolveLocalUserChatJobDurationMs(metadata.queuedAt),
         });
         return { didMutate: true, outcome: 'failed' };
     }
@@ -315,28 +357,34 @@ async function synchronizeLocalUserChatJob(
  *
  * The report is best-effort telemetry shown in the admin task details, so any read or
  * persistence failure only logs a warning instead of failing the finished chat answer.
+ *
+ * @returns The report of the answered message, or `null` when the runner wrote none.
  */
 async function persistLocalUserChatJobRunReportIfPresent(
     job: UserChatJobRecord,
     agentDirectoryPath: string,
     metadata: LocalUserChatJobMetadata,
-): Promise<void> {
+): Promise<AgentMessageRunReport | null> {
     try {
         const reportFileContent = await readOptionalTextFile(
             join(agentDirectoryPath, buildAgentMessageRunReportPath(metadata.finishedPath)),
         );
         const report = reportFileContent === null ? null : parseAgentMessageRunReport(reportFileContent);
         if (!report) {
-            return;
+            return null;
         }
 
         await persistUserChatJobRunReport(job, report);
+
+        return report;
     } catch (error) {
         console.warn('[local-chat-runner] run_report_sync_failed', {
             chatId: job.chatId,
             jobId: job.id,
             error,
         });
+
+        return null;
     }
 }
 
@@ -451,9 +499,61 @@ async function removeQueuedLocalMessageIfPresent(metadata: LocalUserChatJobMetad
         return;
     }
 
-    await rm(join(resolveLocalAgentRootPath(), metadata.agentDirectoryName, metadata.queuedPath), {
-        force: true,
-    }).catch(() => undefined);
+    const agentDirectoryPath = join(resolveLocalAgentRootPath(), metadata.agentDirectoryName);
+
+    await rm(join(agentDirectoryPath, metadata.queuedPath), { force: true }).catch(() => undefined);
+    await removeLocalAgentPlannedMessagesSidecar(agentDirectoryPath, metadata);
+}
+
+/**
+ * Applies planned-message commands without preventing an already answered message from completing.
+ *
+ * @returns The applied commands, or an empty list when the sidecar could not be applied.
+ */
+async function applyLocalAgentPlannedMessageCommandsIfPossible(
+    options: Parameters<typeof applyLocalAgentPlannedMessageCommands>[0],
+): Promise<ReadonlyArray<AppliedAgentPlannedMessageCommand>> {
+    try {
+        return await applyLocalAgentPlannedMessageCommands(options);
+    } catch (error) {
+        console.warn('[local-chat-runner] planned_messages_sidecar_apply_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            error,
+        });
+
+        return [];
+    }
+}
+
+/**
+ * Builds the chips of one answered message without preventing it from completing.
+ *
+ * The chips only enrich the answer, so a failure to resolve them never hides an answer the
+ * agent already produced.
+ *
+ * @returns Tool calls rendered as chips below the answer, or an empty list when they failed.
+ */
+async function createAnsweredMessageChipToolCallsIfPossible(options: {
+    readonly job: UserChatJobRecord;
+    readonly appliedPlannedMessageCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
+    readonly touchedProjectNames: ReadonlyArray<string>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    try {
+        return await createAnsweredMessageChipToolCalls({
+            agentPermanentId: options.job.agentPermanentId,
+            appliedPlannedMessageCommands: options.appliedPlannedMessageCommands,
+            touchedProjectNames: options.touchedProjectNames,
+        });
+    } catch (error) {
+        console.warn('[local-chat-runner] message_chips_build_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            error,
+        });
+
+        return [];
+    }
 }
 
 /**
@@ -479,18 +579,6 @@ function isLocalUserChatJobTimedOut(metadata: LocalUserChatJobMetadata): boolean
     return Number.isFinite(queuedAtMs) && Date.now() - queuedAtMs >= LOCAL_USER_CHAT_JOB_ANSWER_TIMEOUT_MS;
 }
 
-/**
- * Resolves elapsed time since the local message was queued.
- */
-function resolveLocalUserChatJobDurationMs(queuedAt: string): number | undefined {
-    const queuedAtMs = Date.parse(queuedAt);
-    if (!Number.isFinite(queuedAtMs)) {
-        return undefined;
-    }
-
-    return Math.max(0, Date.now() - queuedAtMs);
-}
-
 /**
  * Returns true when one filesystem error indicates a missing path.
  */

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/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/userChatTimeout/createTimeoutWakeUpMessage.ts

@@ -1,20 +1,28 @@
 import { spaceTrim } from 'spacetrim';
+import { formatTimeoutDurationHuman } from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
 
 /**
  * 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.
+ *
  * @private internal utility of userChatTimeout
  */
 export function createTimeoutWakeUpMessage(options: {
     readonly timeoutId: string;
     readonly durationMs: number;
+    readonly intervalMs?: number | null;
     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) => `
-            ⏱️ Timeout elapsed after ${options.durationMs}ms.
+            ${headline}
             timeoutId: ${options.timeoutId}
             ${message ? block(message) : ''}
         `,