@promptbook/cli 0.114.0-3 → 0.114.0-30

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

@@ -0,0 +1,73 @@
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { isAgentGoalChatId } from '../agentGoalChat/agentGoalChatIdentity';
+import type { UserChatTimeoutRecord } from '../userChatTimeout/UserChatTimeoutRecord';
+import { resolvePlannedMessageEndReason } from './resolvePlannedMessageEndReason';
+import { resolvePlannedMessageLifecycle } from './resolvePlannedMessageLifecycle';
+import { resolvePlannedMessageRecurrenceKind } from './resolvePlannedMessageRecurrenceKind';
+
+/**
+ * Everything needed to turn one stored timeout into a manager row.
+ *
+ * @private type of `mapPlannedMessageManagerRecord`
+ */
+type MapPlannedMessageManagerRecordOptions = {
+    readonly plannedMessage: UserChatTimeoutRecord;
+    readonly usernamesById: ReadonlyMap<number, string>;
+    readonly agentNamesByPermanentId: ReadonlyMap<string, string | null>;
+
+    /**
+     * Moment the stage of the planned message is judged at.
+     */
+    readonly atDate: Date;
+};
+
+/**
+ * Maps one stored timeout into the row shown by the admin planned-message manager.
+ *
+ * The stage and the ending reason are derived here once, so every later step — filtering, counting,
+ * and rendering — reads the same answer instead of judging the raw columns again.
+ *
+ * @param options - Stored timeout with the names of its agent and owner.
+ * @returns Planned-message manager row.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function mapPlannedMessageManagerRecord(
+    options: MapPlannedMessageManagerRecordOptions,
+): PlannedMessageManagerRecord {
+    const { plannedMessage, usernamesById, agentNamesByPermanentId, atDate } = options;
+    const lifecycle = resolvePlannedMessageLifecycle(plannedMessage, atDate);
+
+    return {
+        timeoutId: plannedMessage.timeoutId,
+        status: plannedMessage.status,
+        lifecycle,
+        recurrenceKind: resolvePlannedMessageRecurrenceKind(plannedMessage),
+        endReason: lifecycle === 'ENDED' ? resolvePlannedMessageEndReason(plannedMessage, atDate) : null,
+        message: plannedMessage.message,
+
+        createdAt: plannedMessage.createdAt,
+        updatedAt: plannedMessage.updatedAt,
+        dueAt: plannedMessage.dueAt,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        lastFiredAt: plannedMessage.lastFiredAt,
+        completedAt: plannedMessage.completedAt,
+        cancelRequestedAt: plannedMessage.cancelRequestedAt,
+        pausedAt: plannedMessage.pausedAt,
+
+        recurrenceIntervalMs: plannedMessage.recurrenceIntervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
+        attemptCount: plannedMessage.attemptCount,
+        failureReason: plannedMessage.failureReason,
+
+        userId: plannedMessage.userId,
+        username: usernamesById.get(plannedMessage.userId) ?? null,
+        agentPermanentId: plannedMessage.agentPermanentId,
+        agentName: agentNamesByPermanentId.get(plannedMessage.agentPermanentId) ?? null,
+        chatId: plannedMessage.chatId,
+        isAgentGoalChat: isAgentGoalChatId(plannedMessage.chatId),
+    };
+}

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

@@ -0,0 +1,76 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import type { UpdateManagedPlannedMessageRequest } from './updateManagedPlannedMessage';
+
+/**
+ * Fields one administrator request may carry, in the order they are read.
+ *
+ * @private constant of `parsePlannedMessageManagerUpdateRequest`
+ */
+const PLANNED_MESSAGE_UPDATE_REQUEST_FIELDS = [
+    'message',
+    'milliseconds',
+    'cronExpression',
+    'startsAt',
+    'endsAt',
+    'maxRunCount',
+] as const satisfies ReadonlyArray<keyof UpdateManagedPlannedMessageRequest>;
+
+/**
+ * Parses the untrusted body of one planned-message change request.
+ *
+ * Only the presence of each field is decided here — what a field is allowed to contain stays with the
+ * shared planned-message service, so an administrator and an agent are held to one set of rules.
+ *
+ * @param rawBody - Parsed JSON body of the request.
+ * @returns Requested change, carrying exactly the fields that were really sent.
+ * @throws {ParseError} When the body is not an object, carries no change, or holds an invalid `isPaused`.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function parsePlannedMessageManagerUpdateRequest(rawBody: unknown): UpdateManagedPlannedMessageRequest {
+    if (typeof rawBody !== 'object' || rawBody === null || Array.isArray(rawBody)) {
+        throw new ParseError(
+            spaceTrim(`
+                Invalid planned-message change.
+
+                - The request body must be a **JSON object** describing the change.
+            `),
+        );
+    }
+
+    const requestBody = rawBody as Record<string, unknown>;
+    const parsedRequest: Record<string, unknown> = {};
+
+    for (const fieldName of PLANNED_MESSAGE_UPDATE_REQUEST_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(requestBody, fieldName)) {
+            parsedRequest[fieldName] = requestBody[fieldName];
+        }
+    }
+
+    if (Object.prototype.hasOwnProperty.call(requestBody, 'isPaused')) {
+        if (typeof requestBody.isPaused !== 'boolean') {
+            throw new ParseError(
+                spaceTrim(`
+                    Invalid planned-message change.
+
+                    - \`isPaused\` must be \`true\` to hold the planned message back, or \`false\` to let it go again.
+                `),
+            );
+        }
+
+        parsedRequest.isPaused = requestBody.isPaused;
+    }
+
+    if (Object.keys(parsedRequest).length === 0) {
+        throw new ParseError(
+            spaceTrim(`
+                Nothing to change in this planned message.
+
+                - Pass at least one of \`cronExpression\`, \`milliseconds\`, \`startsAt\`, \`endsAt\`, \`maxRunCount\`, \`message\`, or \`isPaused\`.
+            `),
+        );
+    }
+
+    return parsedRequest as UpdateManagedPlannedMessageRequest;
+}

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

@@ -0,0 +1,59 @@
+import { resolvePlannedMessageRecurrenceKind } from './resolvePlannedMessageRecurrenceKind';
+
+/**
+ * Why one planned message stopped waking its agent.
+ *
+ * `null` means the planned message is not over, or that nothing in its own schedule explains the end
+ * — a cancelled or failed message ends for a reason outside its schedule.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageEndReason = 'MAX_RUNS_REACHED' | 'ENDING_DATE_PASSED' | 'SINGLE_RUN_DONE' | null;
+
+/**
+ * Stored fields deciding why one planned message is over.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageEndReasonInput = {
+    readonly recurrenceIntervalMs: number | null;
+    readonly cronExpression: string | null;
+    readonly endsAt: string | null;
+    readonly maxRunCount: number | null;
+    readonly runCount: number;
+};
+
+/**
+ * Resolves why one finished planned message will never wake its agent again.
+ *
+ * The bounds are read in the same order the scheduler applies them, so the manager explains an ended
+ * plan exactly the way it really ended.
+ *
+ * @param plannedMessage - Stored planned message that is already over.
+ * @param atDate - Moment the ending is judged at.
+ * @returns Reason the plan is over, or `null` when its schedule does not explain the end.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageEndReason(
+    plannedMessage: PlannedMessageEndReasonInput,
+    atDate: Date,
+): PlannedMessageEndReason {
+    if (plannedMessage.maxRunCount !== null && plannedMessage.runCount >= plannedMessage.maxRunCount) {
+        return 'MAX_RUNS_REACHED';
+    }
+
+    if (plannedMessage.endsAt !== null) {
+        const endsAtTime = Date.parse(plannedMessage.endsAt);
+
+        if (Number.isFinite(endsAtTime) && endsAtTime <= atDate.getTime()) {
+            return 'ENDING_DATE_PASSED';
+        }
+    }
+
+    if (resolvePlannedMessageRecurrenceKind(plannedMessage) === 'ONCE') {
+        return 'SINGLE_RUN_DONE';
+    }
+
+    return null;
+}

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

@@ -0,0 +1,99 @@
+import type { UserChatTimeoutStatus } from '../userChatTimeout/UserChatTimeoutRecord';
+
+/**
+ * Stage one planned message is in, as shown by the planned-message manager.
+ *
+ * The stored `UserChatTimeoutStatus` alone cannot answer this: a queued planned message may be
+ * waiting for its own starting date, may be paused, or may already have a cancellation on its way,
+ * and all three look like `QUEUED` in the database.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageLifecycle =
+    | 'ONGOING'
+    | 'SCHEDULED'
+    | 'NOT_STARTED'
+    | 'PAUSED'
+    | 'CANCELLED'
+    | 'ENDED'
+    | 'FAILED';
+
+/**
+ * Stored fields needed to tell which stage one planned message is in.
+ *
+ * Both a durable timeout row and one manager row satisfy this shape, so the very same rule decides
+ * the stage on the server and in the browser.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageLifecycleInput = {
+    readonly status: UserChatTimeoutStatus;
+    readonly pausedAt: string | null;
+    readonly cancelRequestedAt: string | null;
+    readonly startsAt: string | null;
+};
+
+/**
+ * Resolves the stage one planned message is in.
+ *
+ * @param plannedMessage - Stored planned message.
+ * @param atDate - Moment the stage is judged at.
+ * @returns Stage of the planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageLifecycle(
+    plannedMessage: PlannedMessageLifecycleInput,
+    atDate: Date,
+): PlannedMessageLifecycle {
+    if (plannedMessage.status === 'RUNNING') {
+        return 'ONGOING';
+    }
+
+    if (plannedMessage.status === 'FAILED') {
+        return 'FAILED';
+    }
+
+    if (plannedMessage.status === 'CANCELLED') {
+        return 'CANCELLED';
+    }
+
+    if (plannedMessage.status === 'COMPLETED') {
+        return 'ENDED';
+    }
+
+    // Note: A cancellation is requested on the row first and only turned into `CANCELLED` by the
+    //       worker, so a queued row carrying that request is already on its way out
+    if (plannedMessage.cancelRequestedAt !== null) {
+        return 'CANCELLED';
+    }
+
+    if (plannedMessage.pausedAt !== null) {
+        return 'PAUSED';
+    }
+
+    if (isPlannedMessageWaitingForStartingDate(plannedMessage.startsAt, atDate)) {
+        return 'NOT_STARTED';
+    }
+
+    return 'SCHEDULED';
+}
+
+/**
+ * Determines whether one planned message may not wake its agent yet because its window has not opened.
+ *
+ * @param startsAt - Moment before which the planned message never wakes the agent.
+ * @param atDate - Moment the stage is judged at.
+ * @returns `true` while the starting date is still ahead.
+ *
+ * @private function of `resolvePlannedMessageLifecycle`
+ */
+function isPlannedMessageWaitingForStartingDate(startsAt: string | null, atDate: Date): boolean {
+    if (startsAt === null) {
+        return false;
+    }
+
+    const startsAtTime = Date.parse(startsAt);
+
+    return Number.isFinite(startsAtTime) && startsAtTime > atDate.getTime();
+}

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

@@ -0,0 +1,40 @@
+/**
+ * How often one planned message wakes its agent.
+ *
+ * A planned message follows exactly one recurrence rule, so these three kinds are exhaustive.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageRecurrenceKind = 'ONCE' | 'INTERVAL' | 'CRON';
+
+/**
+ * Stored fields deciding how often one planned message repeats.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageRecurrenceInput = {
+    readonly recurrenceIntervalMs: number | null;
+    readonly cronExpression: string | null;
+};
+
+/**
+ * Resolves how often one planned message wakes its agent.
+ *
+ * @param plannedMessage - Stored planned message.
+ * @returns Recurrence kind of the planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export function resolvePlannedMessageRecurrenceKind(
+    plannedMessage: PlannedMessageRecurrenceInput,
+): PlannedMessageRecurrenceKind {
+    if (plannedMessage.cronExpression) {
+        return 'CRON';
+    }
+
+    if (plannedMessage.recurrenceIntervalMs) {
+        return 'INTERVAL';
+    }
+
+    return 'ONCE';
+}

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

@@ -0,0 +1,121 @@
+import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { getUserChatTimeoutById, setAgentScopedUserChatTimeoutPausedState } from '../userChatTimeout';
+import { loadPlannedMessageManagerRecord } from './loadPlannedMessageManagerRecord';
+
+/**
+ * Change requested for one planned message, as it arrives from an administrator.
+ *
+ * Every schedule field is untrusted and validated by the shared planned-message service, exactly the
+ * same way a schedule requested by an agent is. Only `isPaused` is checked before it gets here,
+ * because no later step would check it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type UpdateManagedPlannedMessageRequest = {
+    readonly message?: unknown;
+    readonly milliseconds?: unknown;
+    readonly cronExpression?: unknown;
+    readonly startsAt?: unknown;
+    readonly endsAt?: unknown;
+    readonly maxRunCount?: unknown;
+    readonly isPaused?: boolean;
+};
+
+/**
+ * Outcome of one administrator change to a planned message.
+ *
+ * `busy` means the planned message is firing right now, so its schedule is being consumed by that
+ * very firing and cannot be rewritten underneath it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type UpdateManagedPlannedMessageResult =
+    | { readonly status: 'updated'; readonly plannedMessage: PlannedMessageManagerRecord }
+    | { readonly status: 'not_found' }
+    | { readonly status: 'busy' };
+
+/**
+ * Applies one administrator change to a planned message of any agent.
+ *
+ * The change goes through the very same planned-message service an agent re-plans itself with, so an
+ * administrator can never write a schedule the agent itself could not have written.
+ *
+ * @param timeoutId - Id of the planned message being changed.
+ * @param payload - Requested change, where an absent field keeps its stored value.
+ * @returns Changed planned message, or why it could not be changed.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function updateManagedPlannedMessage(
+    timeoutId: string,
+    payload: UpdateManagedPlannedMessageRequest,
+): Promise<UpdateManagedPlannedMessageResult> {
+    const existingPlannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!existingPlannedMessage) {
+        return { status: 'not_found' };
+    }
+
+    const { agentPermanentId } = existingPlannedMessage;
+
+    if (isPlannedMessageScheduleChangeRequested(payload)) {
+        const updateResult = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.update({
+            agentPermanentId,
+            timeoutId,
+            ...(payload.message === undefined ? {} : { message: payload.message }),
+            ...(payload.milliseconds === undefined ? {} : { milliseconds: payload.milliseconds }),
+            ...(payload.cronExpression === undefined ? {} : { cronExpression: payload.cronExpression }),
+            ...(payload.startsAt === undefined ? {} : { startsAt: payload.startsAt }),
+            ...(payload.endsAt === undefined ? {} : { endsAt: payload.endsAt }),
+            ...(payload.maxRunCount === undefined ? {} : { maxRunCount: payload.maxRunCount }),
+        });
+
+        if (updateResult.status === 'not_found') {
+            return { status: 'not_found' };
+        }
+
+        if (updateResult.status === 'busy') {
+            return { status: 'busy' };
+        }
+    }
+
+    if (payload.isPaused !== undefined) {
+        const pauseResult = await setAgentScopedUserChatTimeoutPausedState({
+            agentPermanentId,
+            timeoutId,
+            isPaused: payload.isPaused,
+        });
+
+        if (!pauseResult.isApplied) {
+            return pauseResult.plannedMessage === null ? { status: 'not_found' } : { status: 'busy' };
+        }
+    }
+
+    const changedPlannedMessage = await loadPlannedMessageManagerRecord(timeoutId);
+
+    if (!changedPlannedMessage) {
+        return { status: 'not_found' };
+    }
+
+    return { status: 'updated', plannedMessage: changedPlannedMessage };
+}
+
+/**
+ * Determines whether one requested change touches the schedule or the text of a planned message.
+ *
+ * @param payload - Requested change.
+ * @returns `true` when anything but the paused state was requested.
+ *
+ * @private function of `updateManagedPlannedMessage`
+ */
+function isPlannedMessageScheduleChangeRequested(payload: UpdateManagedPlannedMessageRequest): boolean {
+    return (
+        payload.message !== undefined ||
+        payload.milliseconds !== undefined ||
+        payload.cronExpression !== undefined ||
+        payload.startsAt !== undefined ||
+        payload.endsAt !== undefined ||
+        payload.maxRunCount !== undefined
+    );
+}

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

@@ -0,0 +1,200 @@
+import type { PlannedMessageEndReason } from './plannedMessageManager/resolvePlannedMessageEndReason';
+import type { PlannedMessageLifecycle } from './plannedMessageManager/resolvePlannedMessageLifecycle';
+import type { PlannedMessageRecurrenceKind } from './plannedMessageManager/resolvePlannedMessageRecurrenceKind';
+import type { UserChatTimeoutStatus } from './userChatTimeout/UserChatTimeoutRecord';
+
+/**
+ * One planned message (durable chat timeout) as shown in the admin planned-message manager.
+ *
+ * This is the whole planned message, not the queue view of it the task manager shows: it carries the
+ * schedule the agent planned, where that plan stands now, and who it belongs to.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerRecord = {
+    timeoutId: string;
+    status: UserChatTimeoutStatus;
+    lifecycle: PlannedMessageLifecycle;
+    recurrenceKind: PlannedMessageRecurrenceKind;
+    endReason: PlannedMessageEndReason;
+    message: string | null;
+
+    createdAt: string;
+    updatedAt: string;
+    dueAt: string;
+    startsAt: string | null;
+    endsAt: string | null;
+    lastFiredAt: string | null;
+    completedAt: string | null;
+    cancelRequestedAt: string | null;
+    pausedAt: string | null;
+
+    recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    maxRunCount: number | null;
+    runCount: number;
+    attemptCount: number;
+    failureReason: string | null;
+
+    userId: number;
+    username: string | null;
+    agentPermanentId: string;
+    agentName: string | null;
+    chatId: string;
+
+    /**
+     * True when the planned message lives in the agent's own goal chat, which is where an agent plans
+     * its own work.
+     */
+    isAgentGoalChat: boolean;
+};
+
+/**
+ * Full payload returned by the admin planned-message listing endpoint.
+ *
+ * The whole bounded set is returned at once, so filtering, sorting, and counting all see the same
+ * rows and can never disagree with each other.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerListResponse = {
+    items: Array<PlannedMessageManagerRecord>;
+    generatedAt: string;
+
+    /**
+     * True when more planned messages exist than the endpoint is willing to return at once.
+     */
+    hasMore: boolean;
+};
+
+/**
+ * Stage filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerView =
+    | 'active'
+    | 'scheduled'
+    | 'not-started'
+    | 'ongoing'
+    | 'paused'
+    | 'finished'
+    | 'all';
+
+/**
+ * Recurrence (frequency) filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerRecurrenceFilter = 'all' | PlannedMessageRecurrenceKind;
+
+/**
+ * Last-run filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerLastRunFilter = 'all' | 'never' | 'hour' | 'day' | 'week' | 'older';
+
+/**
+ * Sortable planned-message manager columns.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerSortField =
+    | 'plannedMessage'
+    | 'agent'
+    | 'frequency'
+    | 'nextRun'
+    | 'lastRun'
+    | 'runs'
+    | 'state';
+
+/**
+ * Change requested for one planned message by an administrator.
+ *
+ * Leaving a field out keeps it as it is and passing `null` removes the bound, exactly like the
+ * re-planning an agent can do itself.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerUpdatePayload = {
+    message?: string;
+    milliseconds?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
+
+    /**
+     * Whether the planned message should be held back from waking its agent.
+     */
+    isPaused?: boolean;
+};
+
+/**
+ * Route of the admin planned-message manager API.
+ *
+ * @private internal admin utility of Agents Server
+ */
+const ADMIN_PLANNED_MESSAGES_API_PATH = '/api/admin/planned-messages';
+
+/**
+ * Fetches every planned message of this server for the admin manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $fetchAdminPlannedMessages(): Promise<PlannedMessageManagerListResponse> {
+    const response = await fetch(ADMIN_PLANNED_MESSAGES_API_PATH, { method: 'GET' });
+
+    if (!response.ok) {
+        const payload = await response.json().catch(() => ({}));
+        throw new Error(payload.error || 'Failed to load planned messages.');
+    }
+
+    return (await response.json()) as PlannedMessageManagerListResponse;
+}
+
+/**
+ * Applies one administrator change to a planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $updateAdminPlannedMessage(
+    timeoutId: string,
+    payload: PlannedMessageManagerUpdatePayload,
+): Promise<PlannedMessageManagerRecord> {
+    const response = await fetch(`${ADMIN_PLANNED_MESSAGES_API_PATH}/${encodeURIComponent(timeoutId)}`, {
+        method: 'PATCH',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+    });
+
+    const data = (await response.json().catch(() => ({}))) as {
+        plannedMessage?: PlannedMessageManagerRecord;
+        error?: string;
+    };
+
+    if (!response.ok || !data.plannedMessage) {
+        throw new Error(data.error || 'Failed to update the planned message.');
+    }
+
+    return data.plannedMessage;
+}
+
+/**
+ * Cancels one planned message so it never wakes its agent again.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $cancelAdminPlannedMessage(timeoutId: string): Promise<void> {
+    const response = await fetch(`${ADMIN_PLANNED_MESSAGES_API_PATH}/${encodeURIComponent(timeoutId)}`, {
+        method: 'DELETE',
+    });
+
+    if (!response.ok) {
+        const payload = await response.json().catch(() => ({}));
+        throw new Error(payload.error || 'Failed to cancel the planned message.');
+    }
+}