@promptbook/cli 0.114.0-13 → 0.114.0-18

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.');
+    }
+}