@promptbook/cli 0.114.0-3 → 0.114.0-30

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/parseFederatedServers.ts

@@ -0,0 +1,14 @@
+import type { string_promptbook_server_url } from '@promptbook-local/types';
+
+/**
+ * Parses a comma-separated federated-server metadata value.
+ *
+ * @param value - Raw stored metadata value.
+ * @returns Normalized non-empty server URL values.
+ */
+export function parseFederatedServers(value: string | null | undefined): Array<string_promptbook_server_url> {
+    return (value || '')
+        .split(',')
+        .map((serverUrl) => serverUrl.trim())
+        .filter((serverUrl): serverUrl is string_promptbook_server_url => serverUrl !== '');
+}

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

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

@@ -0,0 +1,191 @@
+import type {
+    PlannedMessageManagerLastRunFilter,
+    PlannedMessageManagerRecord,
+    PlannedMessageManagerRecurrenceFilter,
+    PlannedMessageManagerView,
+} from '../plannedMessagesAdmin';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * Stages shown by each planned-message manager view.
+ *
+ * This is the single place deciding what "active", "finished",... mean, so the tabs, the counters
+ * shown on them, and the listed rows can never describe different sets of planned messages.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export const PLANNED_MESSAGE_LIFECYCLES_BY_VIEW: Record<
+    PlannedMessageManagerView,
+    ReadonlyArray<PlannedMessageLifecycle>
+> = {
+    active: ['ONGOING', 'SCHEDULED', 'NOT_STARTED', 'PAUSED'],
+    scheduled: ['SCHEDULED'],
+    'not-started': ['NOT_STARTED'],
+    ongoing: ['ONGOING'],
+    paused: ['PAUSED'],
+    finished: ['CANCELLED', 'ENDED', 'FAILED'],
+    all: ['ONGOING', 'SCHEDULED', 'NOT_STARTED', 'PAUSED', 'CANCELLED', 'ENDED', 'FAILED'],
+};
+
+/**
+ * Age of the newest wake-up still matching each last-run filter, in milliseconds.
+ *
+ * @private constant of `filterPlannedMessages`
+ */
+const PLANNED_MESSAGE_LAST_RUN_WINDOW_MS: Record<'hour' | 'day' | 'week', number> = {
+    hour: 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+};
+
+/**
+ * Filter value meaning "do not narrow by this parameter".
+ *
+ * @private constant of `filterPlannedMessages`
+ */
+const PLANNED_MESSAGE_FILTER_ANY_VALUE = 'all';
+
+/**
+ * Every parameter the planned-message manager can narrow its listing by.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerFilters = {
+    readonly view: PlannedMessageManagerView;
+
+    /**
+     * Permanent id of the agent whose planned messages are listed, or `all` for every agent.
+     */
+    readonly agentPermanentId: string;
+
+    readonly recurrence: PlannedMessageManagerRecurrenceFilter;
+    readonly lastRun: PlannedMessageManagerLastRunFilter;
+
+    /**
+     * Free text matched against the message, its ids, its agent, and its owner.
+     */
+    readonly search: string;
+};
+
+/**
+ * Keeps only the planned messages matching every active filter.
+ *
+ * @param plannedMessages - All planned messages of the server.
+ * @param filters - Parameters the administrator narrowed the listing by.
+ * @param atDate - Moment the last-run windows are measured from.
+ * @returns Matching planned messages, in the order they were given.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function filterPlannedMessages(
+    plannedMessages: ReadonlyArray<PlannedMessageManagerRecord>,
+    filters: PlannedMessageManagerFilters,
+    atDate: Date,
+): Array<PlannedMessageManagerRecord> {
+    const normalizedSearch = filters.search.trim().toLowerCase();
+
+    return plannedMessages.filter(
+        (plannedMessage) =>
+            isPlannedMessageInView(plannedMessage, filters.view) &&
+            isPlannedMessageOfAgent(plannedMessage, filters.agentPermanentId) &&
+            isPlannedMessageOfRecurrence(plannedMessage, filters.recurrence) &&
+            isPlannedMessageLastRunInWindow(plannedMessage, filters.lastRun, atDate) &&
+            isPlannedMessageMatchingSearch(plannedMessage, normalizedSearch),
+    );
+}
+
+/**
+ * Determines whether one planned message belongs to the selected view.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageInView(
+    plannedMessage: PlannedMessageManagerRecord,
+    view: PlannedMessageManagerView,
+): boolean {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW[view].includes(plannedMessage.lifecycle);
+}
+
+/**
+ * Determines whether one planned message belongs to the selected agent.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageOfAgent(plannedMessage: PlannedMessageManagerRecord, agentPermanentId: string): boolean {
+    return (
+        agentPermanentId === PLANNED_MESSAGE_FILTER_ANY_VALUE ||
+        plannedMessage.agentPermanentId.toLowerCase() === agentPermanentId.toLowerCase()
+    );
+}
+
+/**
+ * Determines whether one planned message repeats the selected way.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageOfRecurrence(
+    plannedMessage: PlannedMessageManagerRecord,
+    recurrence: PlannedMessageManagerRecurrenceFilter,
+): boolean {
+    return recurrence === PLANNED_MESSAGE_FILTER_ANY_VALUE || plannedMessage.recurrenceKind === recurrence;
+}
+
+/**
+ * Determines whether one planned message last woke its agent inside the selected window.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageLastRunInWindow(
+    plannedMessage: PlannedMessageManagerRecord,
+    lastRun: PlannedMessageManagerLastRunFilter,
+    atDate: Date,
+): boolean {
+    if (lastRun === PLANNED_MESSAGE_FILTER_ANY_VALUE) {
+        return true;
+    }
+
+    if (plannedMessage.lastFiredAt === null) {
+        return lastRun === 'never';
+    }
+
+    if (lastRun === 'never') {
+        return false;
+    }
+
+    const lastFiredAtTime = Date.parse(plannedMessage.lastFiredAt);
+    if (!Number.isFinite(lastFiredAtTime)) {
+        return false;
+    }
+
+    const lastRunAgeMs = atDate.getTime() - lastFiredAtTime;
+
+    if (lastRun === 'older') {
+        return lastRunAgeMs > PLANNED_MESSAGE_LAST_RUN_WINDOW_MS.week;
+    }
+
+    return lastRunAgeMs <= PLANNED_MESSAGE_LAST_RUN_WINDOW_MS[lastRun];
+}
+
+/**
+ * Determines whether one planned message matches the free-text search.
+ *
+ * @private function of `filterPlannedMessages`
+ */
+function isPlannedMessageMatchingSearch(plannedMessage: PlannedMessageManagerRecord, normalizedSearch: string): boolean {
+    if (normalizedSearch.length === 0) {
+        return true;
+    }
+
+    const searchableValues = [
+        plannedMessage.message,
+        plannedMessage.timeoutId,
+        plannedMessage.agentPermanentId,
+        plannedMessage.agentName,
+        plannedMessage.chatId,
+        plannedMessage.username,
+        String(plannedMessage.userId),
+        plannedMessage.cronExpression,
+    ];
+
+    return searchableValues.some((value) => typeof value === 'string' && value.toLowerCase().includes(normalizedSearch));
+}

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

@@ -0,0 +1,55 @@
+import { loadAgentNamesByPermanentId, loadUsernamesByUserId } from '../adminEntityLookups';
+import type { PlannedMessageManagerListResponse } from '../plannedMessagesAdmin';
+import { listAllUserChatTimeouts } from '../userChatTimeout';
+import { ensureUserChatTimeoutWorkerBootstrapped } from '../userChatTimeout/ensureUserChatTimeoutWorkerBootstrapped';
+import { mapPlannedMessageManagerRecord } from './mapPlannedMessageManagerRecord';
+
+/**
+ * Largest number of planned messages the manager loads at once.
+ *
+ * The whole set is sent to the browser so filtering, counting, and sorting all see the same rows;
+ * this cap keeps that promise affordable on a server with a long planning history.
+ *
+ * @private constant of `getPlannedMessageManagerResponse`
+ */
+const MAX_PLANNED_MESSAGE_MANAGER_ITEMS = 1_000;
+
+/**
+ * Builds the admin planned-message manager payload from live durable timeout state.
+ *
+ * Every planned message of every agent and every user of this server is listed, whether it is still
+ * ahead, firing right now, or already over.
+ *
+ * @returns Planned messages with the moment they were read.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function getPlannedMessageManagerResponse(): Promise<PlannedMessageManagerListResponse> {
+    ensureUserChatTimeoutWorkerBootstrapped();
+
+    // Note: One row above the cap is loaded, purely to tell whether anything was left out
+    const loadedPlannedMessages = await listAllUserChatTimeouts({ limit: MAX_PLANNED_MESSAGE_MANAGER_ITEMS + 1 });
+    const hasMore = loadedPlannedMessages.length > MAX_PLANNED_MESSAGE_MANAGER_ITEMS;
+    const plannedMessages = hasMore
+        ? loadedPlannedMessages.slice(0, MAX_PLANNED_MESSAGE_MANAGER_ITEMS)
+        : loadedPlannedMessages;
+
+    const [usernamesById, agentNamesByPermanentId] = await Promise.all([
+        loadUsernamesByUserId(plannedMessages.map((plannedMessage) => plannedMessage.userId)),
+        loadAgentNamesByPermanentId(plannedMessages.map((plannedMessage) => plannedMessage.agentPermanentId)),
+    ]);
+    const generatedAtDate = new Date();
+
+    return {
+        items: plannedMessages.map((plannedMessage) =>
+            mapPlannedMessageManagerRecord({
+                plannedMessage,
+                usernamesById,
+                agentNamesByPermanentId,
+                atDate: generatedAtDate,
+            }),
+        ),
+        generatedAt: generatedAtDate.toISOString(),
+        hasMore,
+    };
+}

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

@@ -0,0 +1,18 @@
+import { PLANNED_MESSAGE_LIFECYCLES_BY_VIEW } from './filterPlannedMessages';
+import type { PlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+
+/**
+ * Determines whether one planned message is still part of the agent's plans.
+ *
+ * A planned message is still planned while it can wake its agent again — including one held back by a
+ * pause and one whose starting date is still ahead. This is what decides whether it can be re-planned
+ * or cancelled at all, and it is the very same set the `active` view lists.
+ *
+ * @param lifecycle - Stage the planned message is in.
+ * @returns `true` while the planned message is not over.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function isPlannedMessageStillPlanned(lifecycle: PlannedMessageLifecycle): boolean {
+    return PLANNED_MESSAGE_LIFECYCLES_BY_VIEW.active.includes(lifecycle);
+}

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

@@ -0,0 +1,32 @@
+import { loadAgentNamesByPermanentId, loadUsernamesByUserId } from '../adminEntityLookups';
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { getUserChatTimeoutById } from '../userChatTimeout';
+import { mapPlannedMessageManagerRecord } from './mapPlannedMessageManagerRecord';
+
+/**
+ * Loads one planned message in the shape the admin manager shows it in.
+ *
+ * @param timeoutId - Id of the planned message.
+ * @returns Planned-message manager row, or `null` when there is no such planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadPlannedMessageManagerRecord(timeoutId: string): Promise<PlannedMessageManagerRecord | null> {
+    const plannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!plannedMessage) {
+        return null;
+    }
+
+    const [usernamesById, agentNamesByPermanentId] = await Promise.all([
+        loadUsernamesByUserId([plannedMessage.userId]),
+        loadAgentNamesByPermanentId([plannedMessage.agentPermanentId]),
+    ]);
+
+    return mapPlannedMessageManagerRecord({
+        plannedMessage,
+        usernamesById,
+        agentNamesByPermanentId,
+        atDate: new Date(),
+    });
+}