@promptbook/cli 0.114.0-12 → 0.114.0-13

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) : ''}
         `,

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

@@ -0,0 +1,74 @@
+import { markTaskTerminalLogFinished } from '../../taskTerminal/taskTerminalLog';
+import type { UserChatTimeoutRecord, UserChatTimeoutRow } from '../UserChatTimeoutRecord';
+import { getUserChatTimeoutById } from './getUserChatTimeoutById';
+import { isMissingUserChatTimeoutRelationError } from './isMissingUserChatTimeoutRelationError';
+import { mapUserChatTimeoutRow } from './mapUserChatTimeoutRow';
+import { normalizeRecurrenceIntervalMs } from './normalizeRecurrenceIntervalMs';
+import { provideUserChatTimeoutTable } from './provideUserChatTimeoutTable';
+
+/**
+ * Re-arms one fired repeating timeout for its next interval.
+ *
+ * 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 it does not
+ *          repeat 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;
+    }
+
+    const recurrenceIntervalMs = normalizeRecurrenceIntervalMs(existingTimeout.recurrenceIntervalMs);
+
+    if (recurrenceIntervalMs === null || existingTimeout.cancelRequestedAt) {
+        return null;
+    }
+
+    const nowIso = new Date().toISOString();
+    const nextDueAtIso = new Date(Date.now() + recurrenceIntervalMs).toISOString();
+    const userChatTimeoutTable = await provideUserChatTimeoutTable();
+    const { data, error } = await userChatTimeoutTable
+        .update({
+            status: 'QUEUED',
+            updatedAt: nowIso,
+            queuedAt: nowIso,
+            dueAt: nextDueAtIso,
+            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.ts

@@ -13,6 +13,7 @@ export { markUserChatTimeoutCancelled } from './userChatTimeoutStore/markUserCha
 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';