@promptbook/node 0.112.0-19 → 0.112.0-21

package/esm/index.es.js

@@ -35,7 +35,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-19';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-21';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -23519,8 +23519,9 @@ function createTimeoutSystemMessage(extraInstructions) {
     return spaceTrim$1((block) => `
             Timeout scheduling:
             - Use "set_timeout" to wake this same chat thread in the future.
-            - Use "list_timeouts" to review timeouts across all chats for the same user+agent scope.
-            - "cancel_timeout" accepts a timeout id from any chat in this same user+agent scope.
+            - Use "list_timeouts" to review timeout ids/details across all chats for the same user+agent scope.
+            - "cancel_timeout" accepts either one timeout id or \`allActive: true\` to cancel all active timeouts in this same user+agent scope.
+            - Use "update_timeout" to pause/resume, edit next run, edit recurrence, or update timeout payload details.
             - When one timeout elapses, you will receive a new user-like message that explicitly says it is a timeout wake-up and includes the \`timeoutId\`.
             - Do not claim a timer was set or cancelled unless the tool confirms it.
             ${block(extraInstructions)}
@@ -23647,9 +23648,18 @@ const parseTimeoutToolArgs = {
      */
     cancel(args) {
         const timeoutId = typeof args.timeoutId === 'string' ? args.timeoutId.trim() : '';
+        const allActive = args.allActive === true;
+        if (timeoutId && allActive) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout cancellation must target either one \`timeoutId\` or \`allActive: true\`, not both.
+                `));
+        }
+        if (allActive) {
+            return { allActive: true };
+        }
         if (!timeoutId) {
             throw new PipelineExecutionError(spaceTrim$1(`
-                    Timeout \`timeoutId\` is required.
+                    Timeout \`timeoutId\` is required unless you pass \`allActive: true\`.
                 `));
         }
         return { timeoutId };
@@ -23679,6 +23689,111 @@ const parseTimeoutToolArgs = {
             limit: parsedLimit,
         };
     },
+    /**
+     * Parses `update_timeout` input.
+     */
+    update(args) {
+        const timeoutId = typeof args.timeoutId === 'string' ? args.timeoutId.trim() : '';
+        const allActive = args.allActive === true;
+        if (timeoutId && allActive) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout update must target either one \`timeoutId\` or \`allActive: true\`, not both.
+                `));
+        }
+        if (!timeoutId && !allActive) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout update requires one \`timeoutId\` or \`allActive: true\`.
+                `));
+        }
+        const patch = {};
+        if (typeof args.dueAt === 'string' && args.dueAt.trim().length > 0) {
+            const normalizedDueAt = args.dueAt.trim();
+            const dueAtTimestamp = Date.parse(normalizedDueAt);
+            if (!Number.isFinite(dueAtTimestamp)) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Timeout \`dueAt\` must be one valid ISO timestamp.
+                    `));
+            }
+            patch.dueAt = new Date(dueAtTimestamp).toISOString();
+        }
+        if (typeof args.extendByMs === 'number') {
+            if (!Number.isFinite(args.extendByMs) || args.extendByMs <= 0) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Timeout \`extendByMs\` must be a positive number of milliseconds.
+                    `));
+            }
+            patch.extendByMs = Math.floor(args.extendByMs);
+        }
+        if (patch.dueAt !== undefined && patch.extendByMs !== undefined) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout update cannot include both \`dueAt\` and \`extendByMs\`.
+                `));
+        }
+        if (args.recurrenceIntervalMs === null) {
+            patch.recurrenceIntervalMs = null;
+        }
+        else if (typeof args.recurrenceIntervalMs === 'number') {
+            if (!Number.isFinite(args.recurrenceIntervalMs) || args.recurrenceIntervalMs <= 0) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Timeout \`recurrenceIntervalMs\` must be a positive number of milliseconds or \`null\`.
+                    `));
+            }
+            patch.recurrenceIntervalMs = Math.floor(args.recurrenceIntervalMs);
+        }
+        if (args.message === null) {
+            patch.message = null;
+        }
+        else if (typeof args.message === 'string') {
+            const normalizedMessage = args.message.trim();
+            patch.message = normalizedMessage.length > 0 ? normalizedMessage : null;
+        }
+        if (args.parameters !== undefined) {
+            if (!args.parameters || typeof args.parameters !== 'object' || Array.isArray(args.parameters)) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Timeout \`parameters\` must be one JSON object.
+                    `));
+            }
+            patch.parameters = args.parameters;
+        }
+        if (typeof args.paused === 'boolean') {
+            patch.paused = args.paused;
+        }
+        if (allActive) {
+            if (patch.paused === undefined) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Bulk timeout update with \`allActive: true\` requires \`paused\` to be explicitly set.
+                    `));
+            }
+            const hasSingleOnlyPatch = patch.dueAt !== undefined ||
+                patch.extendByMs !== undefined ||
+                patch.recurrenceIntervalMs !== undefined ||
+                patch.message !== undefined ||
+                patch.parameters !== undefined;
+            if (hasSingleOnlyPatch) {
+                throw new PipelineExecutionError(spaceTrim$1(`
+                        Bulk timeout update only supports the \`paused\` field.
+                    `));
+            }
+            return {
+                allActive: true,
+                paused: patch.paused,
+            };
+        }
+        if (!timeoutId) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout \`timeoutId\` is required for single-timeout updates.
+                `));
+        }
+        if (Object.keys(patch).length === 0) {
+            throw new PipelineExecutionError(spaceTrim$1(`
+                    Timeout update must include at least one editable field.
+                `));
+        }
+        return {
+            timeoutId,
+            patch,
+        };
+    },
 };
 
 /**
@@ -23690,6 +23805,7 @@ const TimeoutToolNames = {
     set: 'set_timeout',
     cancel: 'cancel_timeout',
     list: 'list_timeouts',
+    update: 'update_timeout',
 };
 
 /**
@@ -23722,6 +23838,18 @@ function normalizePromptParameters(rawParameters) {
     return Object.fromEntries(normalizedEntries);
 }
 
+/**
+ * Maximum number of timeout rows rendered into the assistant-visible `list_timeouts` message.
+ *
+ * @private internal USE TIMEOUT constant
+ */
+const MAX_ASSISTANT_VISIBLE_TIMEOUT_ROWS = 20;
+/**
+ * Maximum number of timeout ids rendered in bulk-action summaries.
+ *
+ * @private internal USE TIMEOUT constant
+ */
+const MAX_ASSISTANT_VISIBLE_BULK_TIMEOUT_IDS = 10;
 /**
  * Gets `USE TIMEOUT` tool function implementations.
  *
@@ -23767,6 +23895,23 @@ function createTimeoutToolFunctions() {
             try {
                 const parsedArgs = parseTimeoutToolArgs.cancel(args);
                 const cancelledTimeout = await adapter.cancelTimeout(parsedArgs, runtimeContext);
+                if (cancelledTimeout.status === 'cancelled_all') {
+                    const result = {
+                        action: 'cancel',
+                        status: 'cancelled_all',
+                        cancelledCount: cancelledTimeout.cancelledCount || 0,
+                        cancelledTimeoutIds: cancelledTimeout.cancelledTimeoutIds || [],
+                        hasMore: cancelledTimeout.hasMore,
+                    };
+                    return createToolExecutionEnvelope({
+                        assistantMessage: createBulkCancelAssistantMessage({
+                            cancelledCount: result.cancelledCount || 0,
+                            cancelledTimeoutIds: result.cancelledTimeoutIds || [],
+                            hasMore: result.hasMore,
+                        }),
+                        toolResult: result,
+                    });
+                }
                 const result = {
                     action: 'cancel',
                     status: cancelledTimeout.status,
@@ -23805,7 +23950,10 @@ function createTimeoutToolFunctions() {
                     total: listedTimeouts.total,
                 };
                 return createToolExecutionEnvelope({
-                    assistantMessage: listedTimeouts.total === 1 ? 'Found 1 timeout.' : `Found ${listedTimeouts.total} timeouts.`,
+                    assistantMessage: createListedTimeoutsAssistantMessage({
+                        total: listedTimeouts.total,
+                        items: listedTimeouts.items,
+                    }),
                     toolResult: result,
                 });
             }
@@ -23818,8 +23966,155 @@ function createTimeoutToolFunctions() {
                 return JSON.stringify(result);
             }
         },
+        async [TimeoutToolNames.update](args) {
+            const runtimeContext = resolveTimeoutRuntimeContext(args);
+            const { adapter, disabledResult } = getTimeoutToolRuntimeAdapterOrDisabledResult('update', runtimeContext);
+            if (!adapter || disabledResult) {
+                return JSON.stringify(disabledResult);
+            }
+            try {
+                const parsedArgs = parseTimeoutToolArgs.update(args);
+                const updatedTimeout = await adapter.updateTimeout(parsedArgs, runtimeContext);
+                if (updatedTimeout.status === 'updated_all') {
+                    const result = {
+                        action: 'update',
+                        status: 'updated_all',
+                        updatedCount: updatedTimeout.updatedCount,
+                        matchedCount: updatedTimeout.matchedCount,
+                        updatedTimeoutIds: updatedTimeout.updatedTimeoutIds,
+                        hasMore: updatedTimeout.hasMore,
+                    };
+                    return createToolExecutionEnvelope({
+                        assistantMessage: createBulkUpdateAssistantMessage({
+                            paused: 'allActive' in parsedArgs && parsedArgs.allActive ? parsedArgs.paused : false,
+                            updatedCount: updatedTimeout.updatedCount,
+                            matchedCount: updatedTimeout.matchedCount,
+                            updatedTimeoutIds: updatedTimeout.updatedTimeoutIds,
+                            hasMore: updatedTimeout.hasMore,
+                        }),
+                        toolResult: result,
+                    });
+                }
+                if (updatedTimeout.status === 'not_found') {
+                    const result = {
+                        action: 'update',
+                        status: 'not_found',
+                        timeoutId: updatedTimeout.timeoutId,
+                    };
+                    return createToolExecutionEnvelope({
+                        assistantMessage: 'The timeout was not found.',
+                        toolResult: result,
+                    });
+                }
+                if (updatedTimeout.status === 'conflict') {
+                    const conflictMessage = updatedTimeout.reason === 'running'
+                        ? 'Running timeout cannot be edited.'
+                        : 'Finished timeout cannot be edited.';
+                    const result = {
+                        action: 'update',
+                        status: 'conflict',
+                        timeoutId: updatedTimeout.timeoutId,
+                        message: conflictMessage,
+                    };
+                    return createToolExecutionEnvelope({
+                        assistantMessage: conflictMessage,
+                        toolResult: result,
+                    });
+                }
+                const result = {
+                    action: 'update',
+                    status: 'updated',
+                    timeoutId: updatedTimeout.timeout.timeoutId,
+                    dueAt: updatedTimeout.timeout.dueAt,
+                    paused: updatedTimeout.timeout.paused,
+                    recurrenceIntervalMs: updatedTimeout.timeout.recurrenceIntervalMs,
+                };
+                return createToolExecutionEnvelope({
+                    assistantMessage: `Updated timeout ${JSON.stringify(updatedTimeout.timeout.timeoutId)}.`,
+                    toolResult: result,
+                });
+            }
+            catch (error) {
+                const result = {
+                    action: 'update',
+                    status: 'error',
+                    message: error instanceof Error ? error.message : String(error),
+                };
+                return JSON.stringify(result);
+            }
+        },
     };
 }
+/**
+ * Creates assistant-visible summary for one `list_timeouts` response.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+function createListedTimeoutsAssistantMessage(options) {
+    if (options.total <= 0 || options.items.length === 0) {
+        return 'Found 0 timeouts.';
+    }
+    const visibleItems = options.items.slice(0, MAX_ASSISTANT_VISIBLE_TIMEOUT_ROWS);
+    const summaryRows = visibleItems.map((item, index) => `${index + 1}. ${formatTimeoutListRow(item)}`);
+    const hiddenCount = Math.max(0, options.total - visibleItems.length);
+    if (hiddenCount > 0) {
+        summaryRows.push(`...and ${hiddenCount} more.`);
+    }
+    return [`Found ${options.total} ${options.total === 1 ? 'timeout' : 'timeouts'}:`, ...summaryRows].join('\n');
+}
+/**
+ * Formats one timeout row for assistant-visible timeout listings.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+function formatTimeoutListRow(item) {
+    const normalizedMessage = typeof item.message === 'string' ? item.message.trim() : '';
+    const messageSuffix = normalizedMessage ? ` | message ${JSON.stringify(normalizedMessage)}` : '';
+    const recurrenceSuffix = typeof item.recurrenceIntervalMs === 'number' && item.recurrenceIntervalMs > 0
+        ? ` | recurrence ${item.recurrenceIntervalMs}ms`
+        : '';
+    const pausedSuffix = item.paused ? ' (paused)' : '';
+    return `${item.timeoutId} | ${item.status}${pausedSuffix} | chat ${item.chatId} | due ${item.dueAt}${recurrenceSuffix}${messageSuffix}`;
+}
+/**
+ * Creates assistant-visible summary for bulk timeout cancellation.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+function createBulkCancelAssistantMessage(options) {
+    if (options.cancelledCount <= 0) {
+        return 'No active timeouts were found to cancel.';
+    }
+    const visibleTimeoutIds = options.cancelledTimeoutIds.slice(0, MAX_ASSISTANT_VISIBLE_BULK_TIMEOUT_IDS);
+    const hiddenIdsCount = Math.max(0, options.cancelledTimeoutIds.length - visibleTimeoutIds.length);
+    const hasMoreSuffix = options.hasMore ? ' Additional active timeouts may still exist.' : '';
+    const idsSuffix = visibleTimeoutIds.length > 0
+        ? ` Cancelled ids: ${visibleTimeoutIds.join(', ')}${hiddenIdsCount > 0 ? `, and ${hiddenIdsCount} more.` : '.'}`
+        : '';
+    return `Cancelled ${options.cancelledCount} active ${options.cancelledCount === 1 ? 'timeout' : 'timeouts'}.${idsSuffix}${hasMoreSuffix}`;
+}
+/**
+ * Creates assistant-visible summary for bulk timeout pause/resume updates.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+function createBulkUpdateAssistantMessage(options) {
+    if (options.matchedCount <= 0) {
+        return options.paused
+            ? 'No active queued timeouts were found to pause.'
+            : 'No paused queued timeouts were found to resume.';
+    }
+    const verb = options.paused ? 'Paused' : 'Resumed';
+    const visibleTimeoutIds = options.updatedTimeoutIds.slice(0, MAX_ASSISTANT_VISIBLE_BULK_TIMEOUT_IDS);
+    const hiddenIdsCount = Math.max(0, options.updatedTimeoutIds.length - visibleTimeoutIds.length);
+    const skippedCount = Math.max(0, options.matchedCount - options.updatedCount);
+    const idsSuffix = visibleTimeoutIds.length > 0
+        ? ` Updated ids: ${visibleTimeoutIds.join(', ')}${hiddenIdsCount > 0 ? `, and ${hiddenIdsCount} more.` : '.'}`
+        : '';
+    const skippedSuffix = skippedCount > 0 ? ` Skipped ${skippedCount} due to concurrent changes.` : '';
+    const hasMoreSuffix = options.hasMore ? ' Additional matching timeouts may still exist.' : '';
+    return `${verb} ${options.updatedCount} ${options.updatedCount === 1 ? 'timeout' : 'timeouts'}.${idsSuffix}${skippedSuffix}${hasMoreSuffix}`;
+}
 
 /**
  * Adds `USE TIMEOUT` tool definitions while preserving already registered tools.
@@ -23851,7 +24146,7 @@ function createTimeoutTools(existingTools = []) {
     if (!tools.some((tool) => tool.name === TimeoutToolNames.cancel)) {
         tools.push({
             name: TimeoutToolNames.cancel,
-            description: 'Cancel one previously scheduled timeout within the same user+agent scope, even if it was set in another chat.',
+            description: 'Cancel one timeout by id or cancel all active timeouts across chats for the same user+agent scope.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -23859,15 +24154,18 @@ function createTimeoutTools(existingTools = []) {
                         type: 'string',
                         description: 'Identifier returned earlier by `set_timeout` or `list_timeouts`.',
                     },
+                    allActive: {
+                        type: 'boolean',
+                        description: 'When true, cancel all currently active timeouts across chats in this user+agent scope.',
+                    },
                 },
-                required: ['timeoutId'],
             },
         });
     }
     if (!tools.some((tool) => tool.name === TimeoutToolNames.list)) {
         tools.push({
             name: TimeoutToolNames.list,
-            description: 'List scheduled timeouts across all chats for this same user+agent scope so they can be reviewed or cancelled.',
+            description: 'List timeout details across all chats for this same user+agent scope so they can be reviewed and managed.',
             parameters: {
                 type: 'object',
                 properties: {
@@ -23883,6 +24181,49 @@ function createTimeoutTools(existingTools = []) {
             },
         });
     }
+    if (!tools.some((tool) => tool.name === TimeoutToolNames.update)) {
+        tools.push({
+            name: TimeoutToolNames.update,
+            description: 'Update one timeout (pause/resume, next run, recurrence, payload) or pause/resume all active queued timeouts across chats.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    timeoutId: {
+                        type: 'string',
+                        description: 'Identifier returned earlier by `set_timeout` or `list_timeouts` for one timeout update.',
+                    },
+                    allActive: {
+                        type: 'boolean',
+                        description: 'When true, run one bulk pause/resume across all active queued timeouts in this same user+agent scope.',
+                    },
+                    paused: {
+                        type: 'boolean',
+                        description: 'Pause (`true`) or resume (`false`) one timeout; with `allActive: true` this pauses/resumes all active queued timeouts.',
+                    },
+                    dueAt: {
+                        type: 'string',
+                        description: 'Set the next run timestamp (ISO string). Cannot be used with `extendByMs`.',
+                    },
+                    extendByMs: {
+                        type: 'number',
+                        description: 'Move next run by this many milliseconds. Cannot be used with `dueAt`.',
+                    },
+                    recurrenceIntervalMs: {
+                        type: 'number',
+                        description: 'Set recurrence interval in milliseconds; pass `null` to disable recurrence.',
+                    },
+                    message: {
+                        type: 'string',
+                        description: 'Set wake-up message text for this timeout; pass empty string to clear.',
+                    },
+                    parameters: {
+                        type: 'object',
+                        description: 'Replace stored JSON parameters passed back when timeout fires.',
+                    },
+                },
+            },
+        });
+    }
     return tools;
 }
 
@@ -23904,7 +24245,7 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
      * Short one-line description of `USE TIMEOUT`.
      */
     get description() {
-        return 'Enable timeout wake-ups plus scoped timeout listing/cancellation across chats.';
+        return 'Enable timeout wake-ups plus scoped timeout listing, updates, and cancellation across chats.';
     }
     /**
      * Icon for this commitment.
@@ -23926,8 +24267,9 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
             - The agent uses \`set_timeout\` to schedule a future wake-up in the same chat thread.
             - The tool returns immediately while the timeout is stored and executed by the runtime later.
             - The wake-up arrives as a new user-like timeout message in the same conversation.
-            - The agent can inspect known timeouts via \`list_timeouts\`.
-            - The agent can cancel an existing timeout by \`timeoutId\` via \`cancel_timeout\`, including timeouts created in another chat.
+            - The agent can inspect known timeout details via \`list_timeouts\`.
+            - The agent can cancel one timeout by \`timeoutId\` or cancel all active timeouts via \`cancel_timeout\`.
+            - The agent can pause/resume and edit timeout details via \`update_timeout\`.
             - Commitment content is treated as optional timeout policy instructions.
 
             ## Examples
@@ -23957,6 +24299,7 @@ class UseTimeoutCommitmentDefinition extends BaseCommitmentDefinition {
             [TimeoutToolNames.set]: 'Set timer',
             [TimeoutToolNames.cancel]: 'Cancel timer',
             [TimeoutToolNames.list]: 'List timers',
+            [TimeoutToolNames.update]: 'Update timer',
         };
     }
     /**