@promptbook/node 0.114.0-12 → 0.114.0-13

package/umd/index.umd.js

@@ -47,7 +47,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-12';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-13';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -5238,7 +5238,7 @@
             - You have 100% control over every project folder: create, read, modify, and delete files there, run scripts and commands inside it, and keep any persistent data you need between conversations.
             - When the user asks you to build something (for example a website) or to do longer-term work, create a new project folder \`${AGENT_PROJECTS_DIRECTORY_PATH}/<project-name>/\` (use a short kebab-case name) and do the work inside it. Modify an existing project when the user refers to work you already did.
             - A project can be a git repository — you can run \`git init\` inside a project folder and commit your work there.
-            - Do not touch anything outside the \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory except the queued message file you are answering.
+            - Do not touch anything outside the \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory beyond the file changes allowed at the top of this prompt.
 
             ${block(buildProjectReferenceInstructions(projectsUrlPath))}
             ${block(buildProjectRuntimeInstructions(options.projectRuntimeApi))}
@@ -5294,63 +5294,148 @@
     }
 
     /**
-     * Host used for local project runtimes.
+     * Milliseconds in one second.
+     *
+     * @private internal timeout-chat constant
      */
+    const SECOND_IN_MILLISECONDS = 1000;
     /**
-     * Header used by internal local-runner routes.
+     * Seconds in one minute.
+     *
+     * @private internal timeout-chat constant
      */
-    const USER_CHAT_WORKER_TOKEN_HEADER = 'x-user-chat-worker-token';
-
+    const MINUTE_IN_SECONDS = 60;
+    /**
+     * Seconds in one hour.
+     *
+     * @private internal timeout-chat constant
+     */
+    const HOUR_IN_SECONDS = 60 * MINUTE_IN_SECONDS;
+    /**
+     * Seconds in one day.
+     *
+     * @private internal timeout-chat constant
+     */
+    const HOURS_IN_DAY = 24;
     /**
-     * Title stored on every agent goal chat.
+     * Seconds in one day.
+     *
+     * @private internal timeout-chat constant
      */
+    const DAY_IN_SECONDS = HOURS_IN_DAY * HOUR_IN_SECONDS;
     /**
-     * Internal endpoint used by managed coding agents to plan goal-chat messages.
+     * Converts timeout duration into natural language sentence fragments.
+     *
+     * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+     * Server, and the planned-message prompt section of the agent-folder runner.
+     *
+     * @param milliseconds - Duration or repeat interval in milliseconds.
+     * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+     *
+     * @private internal utility of `<Chat/>` and the Agents Server planned messages
      */
-    const AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH = '/api/internal/agent-goal-chat-planned-messages';
+    function formatTimeoutDurationHuman(milliseconds) {
+        const normalizedMilliseconds = Math.max(0, Math.floor(milliseconds));
+        const totalSeconds = Math.max(1, Math.floor(normalizedMilliseconds / SECOND_IN_MILLISECONDS));
+        if (totalSeconds < MINUTE_IN_SECONDS) {
+            return formatTimeoutUnit(totalSeconds, 'second');
+        }
+        if (totalSeconds < HOUR_IN_SECONDS) {
+            const roundedMinutes = Math.max(1, Math.round(totalSeconds / MINUTE_IN_SECONDS));
+            return formatTimeoutUnit(roundedMinutes, 'minute');
+        }
+        if (totalSeconds < DAY_IN_SECONDS) {
+            const hours = Math.floor(totalSeconds / HOUR_IN_SECONDS);
+            const minutes = Math.floor((totalSeconds % HOUR_IN_SECONDS) / MINUTE_IN_SECONDS);
+            if (minutes === 0) {
+                return formatTimeoutUnit(hours, 'hour');
+            }
+            return `${formatTimeoutUnit(hours, 'hour')} ${formatTimeoutUnit(minutes, 'minute')}`;
+        }
+        const days = Math.floor(totalSeconds / DAY_IN_SECONDS);
+        const hours = Math.floor((totalSeconds % DAY_IN_SECONDS) / HOUR_IN_SECONDS);
+        if (hours === 0) {
+            return formatTimeoutUnit(days, 'day');
+        }
+        return `${formatTimeoutUnit(days, 'day')} ${formatTimeoutUnit(hours, 'hour')}`;
+    }
+    /**
+     * Formats one pluralized timeout unit.
+     *
+     * @private internal timeout-chat helper
+     */
+    function formatTimeoutUnit(value, unit) {
+        return `${value} ${unit}${value === 1 ? '' : 's'}`;
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
 
     /**
      * Builds the planned-message instructions available to an Agents Server-managed coding agent.
      *
-     * Planned messages always target the agent's singleton goal chat, regardless of the chat in which
-     * the command is invoked.
+     * Planned messages always target the agent's singleton goal chat, regardless of the chat in which the
+     * wake-up is planned, and they repeat like `setInterval` until they are cancelled. The sidecar file is
+     * the only channel that changes them, so an answer that merely claims a follow-up was planned changes
+     * nothing — and an answer that changes nothing keeps the current plan running.
+     *
+     * @param sidecar - Sidecar prepared by the Agents Server for the answered message.
+     * @returns Prompt section, or an empty string outside Agents Server-managed runs.
      */
-    function buildAgentGoalChatPromptSection(runtimeApi) {
-        if (!runtimeApi) {
+    function buildAgentGoalChatPromptSection(sidecar) {
+        if (!sidecar) {
             return '';
         }
-        return _spaceTrim.spaceTrim(`
-        ## Planned goal-chat messages
+        return _spaceTrim.spaceTrim((block) => `
+            ## Planned goal-chat messages
 
-        You can plan a future message that wakes you in your singleton goal chat. These commands are available during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
+            You can plan a message that repeatedly wakes you in your singleton goal chat. A planned message works like \`setInterval\`, not like \`setTimeout\`: once planned, it keeps waking you at its interval until you cancel it. This works during every Agents Server-managed chat invocation, not only while answering inside the goal chat.
 
-        - Use \`list_timeouts\` before planning follow-up work so you do not create duplicates.
-        - Use \`set_timeout\` when useful work should resume later. The delay is a positive number of milliseconds and the message should say exactly what your future invocation needs to do.
-        - Use \`cancel_timeout\` with the returned \`timeoutId\` when a planned message is no longer useful.
-        - A fired message appears in the goal chat and invokes you there. If more future work remains, plan the next useful message during that invocation.
+            ${block(buildCurrentPlannedMessagesLines(sidecar.currentPlannedMessages))}
 
-        Run the corresponding authenticated command:
+            Editing \`${sidecar.relativeSidecarPath}\` is the **only** way to change what wakes you. Writing in your answer that you scheduled something does not schedule anything.
 
-        \`\`\`bash
-        # list_timeouts
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"list","agentPermanentId":"${runtimeApi.agentPermanentId}"}'
-
-        # set_timeout
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"set","agentPermanentId":"${runtimeApi.agentPermanentId}","milliseconds":3600000,"message":"Continue the current goal and decide the next concrete action."}'
+            -   **Keeping your planned messages as they are is the default.** When the list above already matches your goal, leave \`commands\` empty — every listed message keeps repeating on its own, and re-planning it would only duplicate it.
+            -   When your goal needs a repeating wake-up that is not listed above, append \`{"action":"set","milliseconds":<repeat interval>,"message":"<what each future invocation must do>"}\` to the \`commands\` array of that file.
+            -   When a listed message no longer matches your goal (for example your goal now says every 10 minutes while the message repeats every 5 minutes), append \`{"action":"cancel","timeoutId":"<timeout id>"}\` and one \`set\` command with the interval your goal really requires.
+            -   When your goal no longer needs a listed message at all, cancel it without planning a replacement.
+            -   Never edit \`version\`, \`agentPermanentId\`, or \`currentPlannedMessages\`.
+            -   The Agents Server applies every command once your answer is finished, and each repetition appears in the goal chat and invokes you there.
+            -   Only mention a planned follow-up in your answer when it is really planned: either you appended the matching \`set\` command, or you kept one of the messages listed above.
+        `);
+    }
+    /**
+     * Renders the already planned messages so the agent can compare them with its goal.
+     *
+     * @param currentPlannedMessages - Planned messages prepared by the Agents Server.
+     * @returns Markdown list, or a sentence stating that nothing is planned yet.
+     *
+     * @private function of `buildAgentGoalChatPromptSection`
+     */
+    function buildCurrentPlannedMessagesLines(currentPlannedMessages) {
+        if (currentPlannedMessages.length === 0) {
+            return 'You currently have no planned messages waiting.';
+        }
+        const plannedMessageLines = currentPlannedMessages.map(createCurrentPlannedMessageLine);
+        return _spaceTrim.spaceTrim((block) => `
+            These planned messages are already waiting for you, so keep them unless they stopped matching your goal:
 
-        # cancel_timeout
-        curl -sS -X POST "$${runtimeApi.serverUrlEnvironmentVariableName}${AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH}" \\
-          -H "Content-Type: application/json" \\
-          -H "${USER_CHAT_WORKER_TOKEN_HEADER}: $${runtimeApi.tokenEnvironmentVariableName}" \\
-          -d '{"action":"cancel","agentPermanentId":"${runtimeApi.agentPermanentId}","timeoutId":"<timeout-id>"}'
-        \`\`\`
-    `);
+            ${block(plannedMessageLines.join('\n'))}
+        `);
+    }
+    /**
+     * Renders one already planned message with the schedule the agent has to compare with its goal.
+     *
+     * @param plannedMessage - One planned message prepared by the Agents Server.
+     * @returns Markdown list item.
+     *
+     * @private function of `buildAgentGoalChatPromptSection`
+     */
+    function createCurrentPlannedMessageLine(plannedMessage) {
+        var _a;
+        const message = ((_a = plannedMessage.message) === null || _a === void 0 ? void 0 : _a.trim()) || 'Continue working towards the current goal.';
+        const schedule = plannedMessage.intervalMs
+            ? `repeats every ${formatTimeoutDurationHuman(plannedMessage.intervalMs)}`
+            : `wakes you once at ${plannedMessage.dueAt}`;
+        return `-   \`${plannedMessage.timeoutId}\` ${schedule}: ${message}`;
     }
 
     // Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
@@ -5381,8 +5466,8 @@
             return '';
         }
         const teammateSections = workspace.manifest.teammates.map((teammate) => {
-            const sourcePath = toPromptPath(path.join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
-            const transcriptPath = toPromptPath(path.join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
+            const sourcePath = toPromptPath$1(path.join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
+            const transcriptPath = toPromptPath$1(path.join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
             const instructions = teammate.instructions.trim() || 'No additional TEAM instructions were provided.';
             return _spaceTrim.spaceTrim(`
             -   ${teammate.agentName}
@@ -5400,7 +5485,7 @@
 
             -   The underlying coding harness is already executing this turn **exactly once**. Never start, queue, or invoke another coding harness, agent runner, or \`ptbk\` command to consult a teammate.
             -   The primary agent remains responsible for the final user-facing \`MESSAGE @Agent\` answer.
-            -   Teammate source files are read-only context. When a teammate consultation occurs, record the actual exchange in a new top-level \`.book\` file in \`${toPromptPath(workspace.relativeWorkspacePath)}\`.
+            -   Teammate source files are read-only context. When a teammate consultation occurs, record the actual exchange in a new top-level \`.book\` file in \`${toPromptPath$1(workspace.relativeWorkspacePath)}\`.
             -   Name each transcript \`<teammate permanent id>--<sequence>.book\`, for example \`${workspace.manifest.teammates[0].permanentId}--01.book\`.
             -   Every transcript must contain alternating \`MESSAGE @${workspace.manifest.primaryAgent.agentName}\` and \`MESSAGE @<teammate name>\` blocks. Do not create a transcript for a teammate that was not consulted.
         `);
@@ -5408,7 +5493,7 @@
     /**
      * Converts a filesystem-relative path into the portable path notation used in prompts.
      */
-    function toPromptPath(path) {
+    function toPromptPath$1(path) {
         return path.replace(/\\/gu, '/');
     }
 
@@ -5421,7 +5506,7 @@
 
                 -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE\` block. In a normal chat it is from \`@User\`; in your internal goal chat it can be from \`@Agent\`.
                 -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
-                ${block(buildAllowedFileChangesPromptLine(options.teamWorkspace))}
+                ${block(buildAllowedFileChangesPromptLine(options))}
 
                 ## Rules for the answering
 
@@ -5457,7 +5542,7 @@
 
                 - You can use \`message\` for message that will be sent immediately after clicking the button, or \`messageDraft\` for message that will be prefilled in the input field for editing before sending.
 
-                ${block(buildAgentGoalChatPromptSection(options.goalChatRuntimeApi))}
+                ${block(buildAgentGoalChatPromptSection(options.plannedMessagesSidecar))}
 
                 ${block(buildAgentProjectsPromptSection(options))}
 
@@ -5471,11 +5556,30 @@
     /**
      * Explains the exact files that one coding harness may change for a user turn.
      */
-    function buildAllowedFileChangesPromptLine(teamWorkspace) {
-        if (!teamWorkspace) {
-            return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory`;
+    function buildAllowedFileChangesPromptLine(options) {
+        const allowedFileChanges = [`files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory`];
+        if (options.teamWorkspace) {
+            allowedFileChanges.push(`new consultation transcripts inside \`${toPromptPath(options.teamWorkspace.relativeWorkspacePath)}\``);
         }
-        return `-   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory and new consultation transcripts inside \`${teamWorkspace.relativeWorkspacePath.replace(/\\/gu, '/')}\``;
+        if (options.plannedMessagesSidecar) {
+            allowedFileChanges.push(`the \`commands\` array of \`${toPromptPath(options.plannedMessagesSidecar.relativeSidecarPath)}\``);
+        }
+        return `-   Do not modify any other file in the repository, except ${formatAllowedFileChanges(allowedFileChanges)}`;
+    }
+    /**
+     * Joins the allowed file-change phrases into one readable enumeration.
+     */
+    function formatAllowedFileChanges(allowedFileChanges) {
+        if (allowedFileChanges.length === 1) {
+            return allowedFileChanges[0];
+        }
+        return `${allowedFileChanges.slice(0, -1).join(', ')} and ${allowedFileChanges[allowedFileChanges.length - 1]}`;
+    }
+    /**
+     * Converts a filesystem-relative path into the portable path notation used in prompts.
+     */
+    function toPromptPath(path) {
+        return path.replace(/\\/gu, '/');
     }
 
     /**