@promptbook/cli 0.114.0-2 → 0.114.0-21

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

@@ -1,19 +1,25 @@
 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 type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+import { createAnsweredMessageChipToolCalls } from '../chatMessageChips/createAnsweredMessageChipToolCalls';
 import { createUserChatJobFailureDetails } from '../userChat/createUserChatJobFailureDetails';
 import { claimNextQueuedUserChatJob } from '../userChat/claimNextQueuedUserChatJob';
 import { finalizeUserChatJob } from '../userChat/finalizeUserChatJob';
-import { getUserChat } from '../userChat/getUserChat';
+import { getUserChatForJobRunner } from '../userChat/getUserChatForJobRunner';
 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,11 +38,20 @@ 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,
     resolveLocalAgentRootPath,
 } from './ensureLocalAgentFolder';
+import { parseFinishedLocalTeamConversations } from './parseLocalTeamConversations';
+import { prepareLocalTeamConversationWorkspace } from './prepareLocalTeamConversationWorkspace';
+import { persistLocalTeamConversations } from './persistLocalTeamConversations';
 import { persistLocalUserChatJobProgressFromRuntimeLog } from './persistLocalUserChatJobProgressFromRuntimeLog';
 
 /**
@@ -145,11 +160,7 @@ async function enqueueLocalUserChatJobWithinTerminalCapture(
     job: UserChatJobRecord,
 ): Promise<ProcessLocalUserChatJobResult> {
     const [chat, agentSourceSnapshot] = await Promise.all([
-        getUserChat({
-            userId: job.userId,
-            agentPermanentId: job.agentPermanentId,
-            chatId: job.chatId,
-        }),
+        getUserChatForJobRunner(job),
         loadLocalAgentSourceSnapshot(job.agentPermanentId),
     ]);
 
@@ -186,6 +197,13 @@ async function enqueueLocalUserChatJobWithinTerminalCapture(
     });
     const queuedMessagePath = join(agentFolder.directoryPath, metadata.queuedPath);
 
+    await prepareLocalTeamConversationWorkspaceIfPossible({
+        job,
+        agentFolder,
+        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');
 
@@ -207,6 +225,38 @@ async function enqueueLocalUserChatJobWithinTerminalCapture(
     return { didMutate: true, outcome: 'queued' };
 }
 
+/**
+ * Creates the optional TEAM workspace without preventing a normal answer when a teammate cannot be resolved.
+ */
+async function prepareLocalTeamConversationWorkspaceIfPossible(
+    options: Parameters<typeof prepareLocalTeamConversationWorkspace>[0],
+): Promise<void> {
+    try {
+        await prepareLocalTeamConversationWorkspace(options);
+    } catch (error) {
+        console.warn('[local-chat-runner] team_workspace_prepare_failed', {
+            agentPermanentId: options.job.agentPermanentId,
+            error,
+        });
+    }
+}
+
+/**
+ * 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.
  */
@@ -224,13 +274,40 @@ 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,
+                job,
+            });
+            const teamToolCalls = await persistLocalTeamConversations({
+                job,
+                conversations: teamConversations,
+            });
+            const chipToolCalls = await createAnsweredMessageChipToolCallsIfPossible({
+                job,
+                appliedPlannedMessageCommands,
+                touchedProjectNames: runReport?.touchedProjectNames || [],
+                projectChanges: runReport?.projectChanges || [],
+                touchedExternalSources: runReport?.touchedExternalSources || [],
+            });
+            const toolCalls = [...teamToolCalls, ...chipToolCalls];
             await persistUserChatJobTerminalState({
                 job,
                 status: 'COMPLETED',
                 provider: LOCAL_USER_CHAT_JOB_PROVIDER,
                 content,
-                generationDurationMs: resolveLocalUserChatJobDurationMs(metadata.queuedAt),
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                executedAt: executionTiming?.executedAt,
+                generationDurationMs: executionTiming?.generationDurationMs,
             });
             return { didMutate: true, outcome: 'completed' };
         }
@@ -247,26 +324,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' };
     }
@@ -284,28 +361,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;
     }
 }
 
@@ -420,9 +503,65 @@ 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>;
+    readonly projectChanges: ReadonlyArray<AgentMessageProjectChange>;
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    try {
+        return await createAnsweredMessageChipToolCalls({
+            agentPermanentId: options.job.agentPermanentId,
+            appliedPlannedMessageCommands: options.appliedPlannedMessageCommands,
+            touchedProjectNames: options.touchedProjectNames,
+            projectChanges: options.projectChanges,
+            touchedExternalSources: options.touchedExternalSources,
+        });
+    } catch (error) {
+        console.warn('[local-chat-runner] message_chips_build_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            error,
+        });
+
+        return [];
+    }
 }
 
 /**
@@ -448,18 +587,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/manGoOnboarding/manGoOnboardingAgentBooks.ts

@@ -8,7 +8,7 @@ import { spaceTrim } from 'spacetrim';
 export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     Book expert
 
-    PERSONA You are expert in book language
+    GOAL Help users work with Book language.
     RULE You can work with the book language and write, modify, or consult the agents based on the book language.
 
     KNOWLEDGE https://live.ptbk.io/api/docs/book-language.md?language=en
@@ -20,10 +20,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Paul Smith & Associés
 
-    PERSONA You are a company lawyer.
-    Your job is to provide legal advice and support to the company and its employees.
-    You are knowledgeable, professional, and detail-oriented.
-    USE SEARCH ENGINE
+    GOAL Provide knowledgeable, professional, and detail-oriented legal advice and support to the company and its employees.
     \`\`\`
 
     RULE You are writing a book in the language the user will ask you.
@@ -37,9 +34,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Mario Ferrari
 
-    PERSONA You are an Italian teacher.
-    You teach the Italian language.
-    You are knowledgeable, professional and detail-oriented.
+    GOAL Teach Italian as a knowledgeable, professional, and detail-oriented teacher.
     RULE Do not chat about anything other than Italian. You can speak Italian or discuss Italian grammar in English.
     LANGUAGES Italian, English
     \`\`\`
@@ -52,9 +47,7 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
     \`\`\`book
     Mario Ferrari
 
-    PERSONA Jste učitel italštiny.
-    Učíte italský jazyk.
-    Jste znalý, profesionální a dbáte na detaily.
+    GOAL Učte italštinu jako znalý, profesionální učitel, který dbá na detaily.
     RULE Nepovídejte si o ničem jiném než o italštině. Můžete mluvit italsky nebo diskutovat o italské gramatice v angličtině.
     LANGUAGES Italština, čeština, angličtina
     \`\`\`
@@ -70,6 +63,6 @@ export const MAN_GO_BOOK_EXPERT_BOOK = spaceTrim(`
 export const MAN_GO_REPLY_REVIEWER_BOOK = spaceTrim(`
     Kontrolor odpovědí
 
-    PERSONA Jste přísný kontrolor odpovědí zákaznické podpory. Porovnáváte návrh odpovědi s definicí agenta (book) - tonalita, délka, jazyk, zakázaná témata a dodržení instrukcí.
+    GOAL Přísně kontrolujte návrhy odpovědí zákaznické podpory proti definici agenta (book): tonalitu, délku, jazyk, zakázaná témata a dodržení instrukcí.
     RULE Odpovídáte výhradně požadovaným JSON polem v jednom \`json\` bloku, nic jiného.
 `);

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime.ts

@@ -65,7 +65,7 @@ export type EvaluateManGoAgentReplyInput = {
 const MAN_GO_TEST_FALLBACK_BOOK = spaceTrim(`
     Agent
 
-    PERSONA Jste užitečný asistent.
+    GOAL Pomáhejte uživatelům jako užitečný asistent.
     RULE Odpovídejte stručně a prakticky.
     CLOSED
 `);
@@ -127,7 +127,7 @@ function createBookPrompt(input: GenerateManGoBookInput): string {
         Requirements:
         - Use the provided name as the agent title.
         - Write natural-language commitments in Czech unless the brief clearly asks for another language.
-        - Include a useful PERSONA, GOAL, and practical RULE commitments derived from the description.
+        - Include a clear GOAL and practical RULE commitments derived from the description.
         - Keep commitment keywords in English.
         - Use Book-language commitments such as WRITING SAMPLE, WRITING RULES, MESSAGE SUFFIX, and NOTE when they fit the agent.
         - Do not use Markdown headings such as \`##\` as a substitute for Book-language commitments.

package/apps/agents-server/src/utils/managementApi/managementApiSchemas.ts

@@ -332,7 +332,7 @@ export const MANAGEMENT_API_EXAMPLES = {
         },
         source: spaceTrim(`
             Support Concierge
-            PERSONA You triage support tickets.
+            GOAL Triage support tickets.
             RULE Escalate billing issues.
         `),
         profile: {
@@ -346,7 +346,7 @@ export const MANAGEMENT_API_EXAMPLES = {
     createAgentRequest: {
         source: spaceTrim(`
             Support Concierge
-            PERSONA You triage support tickets.
+            GOAL Triage support tickets.
             RULE Escalate billing issues.
         `),
         folderId: 12,

package/apps/agents-server/src/utils/messages/parseUseEmailSmtpCredential.ts

@@ -2,7 +2,7 @@ import { isValidEmail } from '../../../../../src/utils/validators/email/isValidE
 import type { SmtpMessageProviderConfiguration } from '../../message-providers/email/smtp/SmtpMessageProvider';
 
 /**
- * Normalized SMTP credential payload expected in wallet secret for USE EMAIL.
+ * Normalized SMTP credential payload expected in wallet secret for agent email.
  */
 export type UseEmailSmtpCredential = SmtpMessageProviderConfiguration & {
     fromAddress?: string;

package/apps/agents-server/src/utils/plannedMessageManager/cancelManagedPlannedMessage.ts

@@ -0,0 +1,35 @@
+import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import { getUserChatTimeoutById } from '../userChatTimeout';
+
+/**
+ * Outcome of cancelling one planned message from the admin manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type CancelManagedPlannedMessageResult = 'cancelled' | 'not_found';
+
+/**
+ * Cancels one planned message of any agent, so it never wakes that agent again.
+ *
+ * The cancelled planned message is kept and keeps being listed as cancelled, because the manager is
+ * also the place where an administrator asks what a planned message did before it stopped.
+ *
+ * @param timeoutId - Id of the planned message being cancelled.
+ * @returns Whether the planned message was cancelled.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function cancelManagedPlannedMessage(timeoutId: string): Promise<CancelManagedPlannedMessageResult> {
+    const existingPlannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!existingPlannedMessage) {
+        return 'not_found';
+    }
+
+    const cancelResult = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.cancel({
+        agentPermanentId: existingPlannedMessage.agentPermanentId,
+        timeoutId,
+    });
+
+    return cancelResult.status === 'cancelled' ? 'cancelled' : 'not_found';
+}

package/apps/agents-server/src/utils/plannedMessageManager/collectPlannedMessageAgentOptions.ts

@@ -0,0 +1,56 @@
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+
+/**
+ * One agent offered by the planned-message agent filter.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageAgentOption = {
+    readonly agentPermanentId: string;
+    readonly agentName: string | null;
+    readonly plannedMessageCount: number;
+};
+
+/**
+ * Collects the agents that really have planned messages, for the agent filter.
+ *
+ * Only agents present in the listing are offered, so the filter can never select an empty result.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @returns Agents sorted by their displayed name.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function collectPlannedMessageAgentOptions(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+): Array<PlannedMessageAgentOption> {
+    const optionsByAgentPermanentId = new Map<string, PlannedMessageAgentOption>();
+
+    for (const plannedMessage of plannedMessages) {
+        const existingOption = optionsByAgentPermanentId.get(plannedMessage.agentPermanentId);
+
+        optionsByAgentPermanentId.set(plannedMessage.agentPermanentId, {
+            agentPermanentId: plannedMessage.agentPermanentId,
+            agentName: existingOption?.agentName ?? plannedMessage.agentName,
+            plannedMessageCount: (existingOption?.plannedMessageCount ?? 0) + 1,
+        });
+    }
+
+    return [...optionsByAgentPermanentId.values()].sort((leftOption, rightOption) =>
+        resolvePlannedMessageAgentOptionLabel(leftOption).localeCompare(
+            resolvePlannedMessageAgentOptionLabel(rightOption),
+        ),
+    );
+}
+
+/**
+ * Resolves the label of one agent filter option.
+ *
+ * @param option - Agent offered by the filter.
+ * @returns Agent name, falling back to its permanent id.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageAgentOptionLabel(option: PlannedMessageAgentOption): string {
+    return option.agentName || option.agentPermanentId;
+}

package/apps/agents-server/src/utils/plannedMessageManager/createPlannedMessageManagerCounters.ts

@@ -0,0 +1,104 @@
+import type { PlannedMessageManagerRecord, PlannedMessageManagerView } from '../plannedMessagesAdmin';
+import { PLANNED_MESSAGE_LIFECYCLES_BY_VIEW } from './filterPlannedMessages';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * How many planned messages stand in each stage right now.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerCounters = {
+    readonly countByLifecycle: Record<PlannedMessageLifecycle, number>;
+    readonly totalCount: number;
+
+    /**
+     * Earliest moment any planned message is going to wake its agent, or `null` when none will.
+     */
+    readonly nextDueAt: string | null;
+};
+
+/**
+ * Stages that still have a wake-up ahead of them.
+ *
+ * @private constant of `createPlannedMessageManagerCounters`
+ */
+const UPCOMING_PLANNED_MESSAGE_LIFECYCLES: ReadonlyArray<PlannedMessageLifecycle> = ['SCHEDULED', 'NOT_STARTED'];
+
+/**
+ * Counts the planned messages of each stage and finds the next wake-up ahead.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @returns Counters rendered above the planned-message table.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function createPlannedMessageManagerCounters(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+): PlannedMessageManagerCounters {
+    const countByLifecycle: Record<PlannedMessageLifecycle, number> = {
+        ONGOING: 0,
+        SCHEDULED: 0,
+        NOT_STARTED: 0,
+        PAUSED: 0,
+        CANCELLED: 0,
+        ENDED: 0,
+        FAILED: 0,
+    };
+    let nextDueAt: string | null = null;
+
+    for (const plannedMessage of plannedMessages) {
+        countByLifecycle[plannedMessage.lifecycle] += 1;
+
+        if (UPCOMING_PLANNED_MESSAGE_LIFECYCLES.includes(plannedMessage.lifecycle)) {
+            nextDueAt = resolveEarlierDate(nextDueAt, plannedMessage.dueAt);
+        }
+    }
+
+    return {
+        countByLifecycle,
+        totalCount: plannedMessages.length,
+        nextDueAt,
+    };
+}
+
+/**
+ * Counts the planned messages one manager view lists.
+ *
+ * @param counters - Counters of every stage.
+ * @param view - View whose size is asked for.
+ * @returns Number of planned messages the view lists before any other filter narrows it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageManagerViewCount(
+    counters: PlannedMessageManagerCounters,
+    view: PlannedMessageManagerView,
+): number {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW[view].reduce(
+        (viewCount, lifecycle) => viewCount + counters.countByLifecycle[lifecycle],
+        0,
+    );
+}
+
+/**
+ * Keeps whichever of two moments comes first.
+ *
+ * @param currentDate - Earliest moment found so far, or `null`.
+ * @param candidateDate - Moment being considered.
+ * @returns Earlier of the two moments.
+ *
+ * @private function of `createPlannedMessageManagerCounters`
+ */
+function resolveEarlierDate(currentDate: string | null, candidateDate: string): string | null {
+    const candidateTime = Date.parse(candidateDate);
+
+    if (!Number.isFinite(candidateTime)) {
+        return currentDate;
+    }
+
+    if (currentDate === null) {
+        return candidateDate;
+    }
+
+    return candidateTime < Date.parse(currentDate) ? candidateDate : currentDate;
+}