@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/languages/translations/english.yaml

@@ -17,6 +17,9 @@ goalChat.plannedMessagesEmptyLabel: No planned messages. The agent will wake up
 goalChat.plannedMessagesLoadErrorLabel: Failed to load planned messages.
 goalChat.plannedMessageDefaultLabel: Planned wake-up
 goalChat.plannedMessageIntervalLabel: Repeats every {interval}
+goalChat.plannedMessageCronLabel: 'Repeats on cron {cron}'
+goalChat.plannedMessageRunCountLabel: '{runCount} of {maxRunCount} runs done'
+goalChat.plannedMessageWindowLabel: 'From {from} to {to}'
 goalChat.plannedMessageCancelLabel: Cancel
 goalChat.plannedMessageCancellingLabel: Cancelling
 common.projects: Projects
@@ -170,6 +173,7 @@ header.chatHistory: Chat history
 header.usageAnalytics: Usage analytics
 header.taskManager: Task manager
 header.vpsTaskManager: Task manager (all servers)
+header.plannedMessageManager: Planned messages
 header.messagesEmails: Messages & Emails
 header.emailServer: Email server
 header.backups: Backups

package/apps/agents-server/src/tools/agentGoalChatTimeoutToolFunctions.ts

@@ -1,5 +1,5 @@
 import { spaceTrim } from 'spacetrim';
-import { formatTimeoutDurationHuman } from '../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import { describeAgentPlannedMessageSchedule } from '../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
 import type { string_javascript_name } from '../../../../src/types/string_person_fullname';
 import type { ToolFunction } from '../../../../src/scripting/javascript/JavascriptExecutionToolsOptions';
 import { createToolExecutionEnvelope } from '../../../../src/commitments/_common/toolExecutionEnvelope';
@@ -9,6 +9,7 @@ import {
     createAgentGoalChatPlannedMessageActions,
     type AgentGoalChatPlannedMessageDependencies,
     type AgentGoalChatPlannedMessageItem,
+    type UpdateAgentGoalChatPlannedMessageResult,
 } from '../utils/agentGoalChat/agentGoalChatPlannedMessageActions';
 import { AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES } from './agentGoalChatTimeoutTools';
 
@@ -41,14 +42,14 @@ export function createAgentGoalChatTimeoutToolFunctions(
                 const agentPermanentId = resolveAgentPermanentId(toolArguments);
                 const result = await actions.set({
                     agentPermanentId,
-                    milliseconds: toolArguments.milliseconds,
+                    ...createPlannedMessageScheduleArguments(toolArguments),
                     message: toolArguments.message,
                 });
 
                 return createToolExecutionEnvelope({
                     assistantMessage: `Planned message ${JSON.stringify(
                         result.timeoutId,
-                    )} ${createPlannedMessageScheduleLabel(result)}.`,
+                    )} ${describeAgentPlannedMessageSchedule(result)}.`,
                     toolResult: result,
                 });
             } catch (error) {
@@ -56,6 +57,27 @@ export function createAgentGoalChatTimeoutToolFunctions(
             }
         },
 
+        async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update](
+            toolArguments: AgentGoalChatTimeoutToolArguments,
+        ): Promise<string> {
+            try {
+                const agentPermanentId = resolveAgentPermanentId(toolArguments);
+                const result = await actions.update({
+                    agentPermanentId,
+                    timeoutId: toolArguments.timeoutId,
+                    ...createPlannedMessageScheduleArguments(toolArguments),
+                    ...(toolArguments.message === undefined ? {} : { message: toolArguments.message }),
+                });
+
+                return createToolExecutionEnvelope({
+                    assistantMessage: createUpdatedPlannedMessageAssistantMessage(result),
+                    toolResult: result,
+                });
+            } catch (error) {
+                return serializeToolError('update', error);
+            }
+        },
+
         async [AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.list](
             toolArguments: AgentGoalChatTimeoutToolArguments,
         ): Promise<string> {
@@ -150,7 +172,7 @@ function createPlannedMessagesAssistantSummary(
     const visiblePlannedMessages = plannedMessages.slice(0, MAX_ASSISTANT_VISIBLE_PLANNED_MESSAGES);
     const summaryRows = visiblePlannedMessages.map((plannedMessage, index) => {
         const message = plannedMessage.message?.trim() || 'Wake up and continue working towards the current goal.';
-        return `${index + 1}. ${plannedMessage.timeoutId} ${createPlannedMessageScheduleLabel(
+        return `${index + 1}. ${plannedMessage.timeoutId} ${describeAgentPlannedMessageSchedule(
             plannedMessage,
         )}: ${message}`;
     });
@@ -170,20 +192,45 @@ function createPlannedMessagesAssistantSummary(
 }
 
 /**
- * Describes when one planned message wakes the agent.
+ * Builds the text shown to the model after one re-planning attempt.
  *
- * @param plannedMessage - Planned message with its repeat interval and nearest execution time.
- * @returns Schedule fragment such as `repeating every 5 minutes (next at ...)`.
+ * @param result - Result of the shared re-planning action.
+ * @returns Assistant-visible sentence telling what really happened to the planned message.
  */
-function createPlannedMessageScheduleLabel(plannedMessage: {
-    readonly dueAt: string;
-    readonly intervalMs: number | null;
-}): string {
-    if (!plannedMessage.intervalMs) {
-        return `at ${plannedMessage.dueAt}`;
+function createUpdatedPlannedMessageAssistantMessage(result: UpdateAgentGoalChatPlannedMessageResult): string {
+    if (result.status === 'updated') {
+        return `Planned message ${JSON.stringify(result.timeoutId)} now ${describeAgentPlannedMessageSchedule(
+            result,
+        )}.`;
+    }
+
+    if (result.status === 'busy') {
+        return `Planned message ${JSON.stringify(
+            result.timeoutId,
+        )} is waking you right now and was left unchanged, so change it again afterwards.`;
     }
 
-    return `repeating every ${formatTimeoutDurationHuman(plannedMessage.intervalMs)} (next at ${plannedMessage.dueAt})`;
+    return 'The planned message was already inactive or was not found.';
+}
+
+/**
+ * Collects the schedule arguments of one planned-message tool call.
+ *
+ * An argument the model did not pass stays absent, so an update changes only the fields it names.
+ *
+ * @param toolArguments - Raw arguments of the tool call.
+ * @returns Schedule fields passed to the shared planned-message actions.
+ */
+function createPlannedMessageScheduleArguments(
+    toolArguments: AgentGoalChatTimeoutToolArguments,
+): AgentGoalChatTimeoutToolArguments {
+    return {
+        ...(toolArguments.milliseconds === undefined ? {} : { milliseconds: toolArguments.milliseconds }),
+        ...(toolArguments.cronExpression === undefined ? {} : { cronExpression: toolArguments.cronExpression }),
+        ...(toolArguments.startsAt === undefined ? {} : { startsAt: toolArguments.startsAt }),
+        ...(toolArguments.endsAt === undefined ? {} : { endsAt: toolArguments.endsAt }),
+        ...(toolArguments.maxRunCount === undefined ? {} : { maxRunCount: toolArguments.maxRunCount }),
+    };
 }
 
 /**
@@ -193,7 +240,7 @@ function createPlannedMessageScheduleLabel(plannedMessage: {
  * @param error - Caught failure.
  * @returns JSON result readable by the model and persisted tool-call inspector.
  */
-function serializeToolError(action: 'set' | 'list' | 'cancel', error: unknown): string {
+function serializeToolError(action: 'set' | 'update' | 'list' | 'cancel', error: unknown): string {
     return JSON.stringify({
         action,
         status: 'error',

package/apps/agents-server/src/tools/agentGoalChatTimeoutTools.ts

@@ -5,10 +5,44 @@ import type { LlmToolDefinition } from '../../../../src/types/LlmToolDefinition'
  */
 export const AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES = {
     set: 'set_timeout',
+    update: 'update_timeout',
     list: 'list_timeouts',
     cancel: 'cancel_timeout',
 } as const;
 
+/**
+ * Schedule parameters shared by the planning and re-planning tools.
+ *
+ * One planned message follows exactly one recurrence rule, bounded by an optional date window and an
+ * optional total number of runs, so both tools describe the very same fields.
+ */
+const AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS = {
+    milliseconds: {
+        type: 'number',
+        description:
+            'Repeat interval in milliseconds between two wake-ups by this planned message (at least 60000). Use either this or `cronExpression`.',
+    },
+    cronExpression: {
+        type: 'string',
+        description:
+            'Five-field cron expression such as `0 9 * * 1-5`, evaluated in the server time zone. Use either this or `milliseconds`.',
+    },
+    maxRunCount: {
+        type: 'number',
+        description:
+            'How many times in total this planned message wakes you, for example 1 for a one-off message. Leave it out to repeat until cancelled.',
+    },
+    startsAt: {
+        type: 'string',
+        description:
+            'ISO date before which the planned message never wakes you, for example `2026-09-01T08:00:00.000Z`.',
+    },
+    endsAt: {
+        type: 'string',
+        description: 'ISO date after which the planned message stops waking you and finishes on its own.',
+    },
+} as const;
+
 /**
  * Adds the Agents Server planned-message tools while preserving already registered tools.
  *
@@ -27,22 +61,42 @@ export function createAgentGoalChatTimeoutTools(
         tools.push({
             name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.set,
             description:
-                'Plan a message that repeatedly wakes you in your singleton goal chat, like `setInterval`. Use this for useful autonomous follow-up towards your current goal; the wake-up is not tied to the human conversation where you schedule it, and it keeps repeating until you cancel it. Do not plan a message that matches one you already planned.',
+                'Plan a message that wakes you in your singleton goal chat, like `setInterval`. Use this for useful autonomous follow-up towards your current goal; the wake-up is not tied to the human conversation where you schedule it, and it keeps repeating until its schedule is over or you cancel it. Do not plan a message that matches one you already planned.',
             parameters: {
                 type: 'object',
                 properties: {
-                    milliseconds: {
-                        type: 'number',
-                        description:
-                            'Repeat interval in milliseconds between two wake-ups by this planned message (at least 60000).',
-                    },
+                    ...AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS,
                     message: {
                         type: 'string',
                         description:
                             'The concrete future instruction or reminder that will be delivered in your goal chat.',
                     },
                 },
-                required: ['milliseconds', 'message'],
+                required: ['message'],
+                additionalProperties: false,
+            },
+        });
+    }
+
+    if (!tools.some((tool) => tool.name === AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update)) {
+        tools.push({
+            name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.update,
+            description:
+                'Change the schedule or the text of one planned goal-chat message without losing its identity. Pass only the fields you want to change; every other field keeps its current value, and `null` removes a bound such as `endsAt`. Prefer this over cancelling and planning the same message again.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    timeoutId: {
+                        type: 'string',
+                        description: 'Identifier returned by `set_timeout` or `list_timeouts`.',
+                    },
+                    ...AGENT_GOAL_CHAT_TIMEOUT_SCHEDULE_PARAMETERS,
+                    message: {
+                        type: 'string',
+                        description: 'New instruction delivered by this planned message in your goal chat.',
+                    },
+                },
+                required: ['timeoutId'],
                 additionalProperties: false,
             },
         });
@@ -52,7 +106,7 @@ export function createAgentGoalChatTimeoutTools(
         tools.push({
             name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.list,
             description:
-                'List your planned goal-chat messages, including their identifiers, repeat intervals, and next execution times, across every conversation in which you were invoked. Keep the listed messages as they are unless they no longer match your goal.',
+                'List your planned goal-chat messages, including their identifiers, whole schedules, and next execution times, across every conversation in which you were invoked. Messages which already finished are left out. Keep the listed messages as they are unless they no longer match your goal.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -74,7 +128,7 @@ export function createAgentGoalChatTimeoutTools(
         tools.push({
             name: AGENT_GOAL_CHAT_TIMEOUT_TOOL_NAMES.cancel,
             description:
-                'Stop one repeating planned goal-chat message by its timeout identifier. List planned messages first when the identifier is not known.',
+                'Stop one planned goal-chat message by its timeout identifier, which also stops all of its remaining repetitions. List planned messages first when the identifier is not known.',
             parameters: {
                 type: 'object',
                 properties: {

package/apps/agents-server/src/utils/adminEntityLookups/loadAgentNamesByPermanentId.ts

@@ -0,0 +1,45 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+
+/**
+ * Minimal agent lookup row needed to name the agent behind one admin row.
+ *
+ * @private type of `loadAgentNamesByPermanentId`
+ */
+type AgentNameLookupRow = Pick<AgentsServerDatabase['public']['Tables']['Agent']['Row'], 'permanentId' | 'agentName'>;
+
+/**
+ * Loads agent names keyed by permanent id, for admin listings that only store the permanent id.
+ *
+ * @param agentPermanentIds - Permanent ids of the agents to name, duplicates allowed.
+ * @returns Agent names keyed by permanent id, empty when nothing was asked for.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadAgentNamesByPermanentId(
+    agentPermanentIds: ReadonlyArray<string>,
+): Promise<Map<string, string | null>> {
+    const uniqueAgentPermanentIds = [...new Set(agentPermanentIds)].filter(Boolean);
+
+    if (uniqueAgentPermanentIds.length === 0) {
+        return new Map();
+    }
+
+    const supabase = $provideSupabaseForServer();
+    const agentTable = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(agentTable)
+        .select('permanentId,agentName')
+        .in('permanentId', uniqueAgentPermanentIds);
+
+    if (error) {
+        throw new Error(`Failed to load admin listing agents: ${error.message}`);
+    }
+
+    return new Map(
+        ((data || []) as Array<AgentNameLookupRow>)
+            .filter((agentRow): agentRow is AgentNameLookupRow & { permanentId: string } => Boolean(agentRow.permanentId))
+            .map((agentRow) => [agentRow.permanentId, agentRow.agentName] as const),
+    );
+}

package/apps/agents-server/src/utils/adminEntityLookups/loadUsernamesByUserId.ts

@@ -0,0 +1,36 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
+import type { AgentsServerDatabase } from '@/src/database/schema';
+
+/**
+ * Minimal user lookup row needed to name the owner of one admin row.
+ *
+ * @private type of `loadUsernamesByUserId`
+ */
+type UsernameLookupRow = Pick<AgentsServerDatabase['public']['Tables']['User']['Row'], 'id' | 'username'>;
+
+/**
+ * Loads usernames keyed by user id, for admin listings that only store the owning user id.
+ *
+ * @param userIds - Ids of the users to name, duplicates allowed.
+ * @returns Usernames keyed by user id, empty when nothing was asked for.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function loadUsernamesByUserId(userIds: ReadonlyArray<number>): Promise<Map<number, string>> {
+    const uniqueUserIds = [...new Set(userIds)];
+
+    if (uniqueUserIds.length === 0) {
+        return new Map();
+    }
+
+    const supabase = $provideSupabaseForServer();
+    const userTable = await $getTableName('User');
+    const { data, error } = await supabase.from(userTable).select('id,username').in('id', uniqueUserIds);
+
+    if (error) {
+        throw new Error(`Failed to load admin listing users: ${error.message}`);
+    }
+
+    return new Map(((data || []) as Array<UsernameLookupRow>).map((userRow) => [userRow.id, userRow.username] as const));
+}

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

@@ -0,0 +1,2 @@
+export { loadAgentNamesByPermanentId } from './adminEntityLookups/loadAgentNamesByPermanentId';
+export { loadUsernamesByUserId } from './adminEntityLookups/loadUsernamesByUserId';