@promptbook/node 0.114.0-12 → 0.114.0-14

package/esm/index.es.js

@@ -29,7 +29,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.114.0-12';
+const PROMPTBOOK_ENGINE_VERSION = '0.114.0-14';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -5220,7 +5220,7 @@ function buildAgentProjectsPromptSection(options = {}) {
             - 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))}
@@ -5276,63 +5276,148 @@ function buildProjectRuntimeInstructions(projectRuntimeApi) {
 }
 
 /**
- * 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$1(`
-        ## Planned goal-chat messages
+    return spaceTrim$1((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$1((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.
@@ -5363,8 +5448,8 @@ function buildAgentTeamPromptSection(workspace) {
         return '';
     }
     const teammateSections = workspace.manifest.teammates.map((teammate) => {
-        const sourcePath = toPromptPath(join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
-        const transcriptPath = toPromptPath(join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
+        const sourcePath = toPromptPath$1(join(workspace.relativeWorkspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName));
+        const transcriptPath = toPromptPath$1(join(workspace.relativeWorkspacePath, `${teammate.permanentId}--01.book`));
         const instructions = teammate.instructions.trim() || 'No additional TEAM instructions were provided.';
         return spaceTrim$1(`
             -   ${teammate.agentName}
@@ -5382,7 +5467,7 @@ function buildAgentTeamPromptSection(workspace) {
 
             -   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.
         `);
@@ -5390,7 +5475,7 @@ function buildAgentTeamPromptSection(workspace) {
 /**
  * Converts a filesystem-relative path into the portable path notation used in prompts.
  */
-function toPromptPath(path) {
+function toPromptPath$1(path) {
     return path.replace(/\\/gu, '/');
 }
 
@@ -5403,7 +5488,7 @@ function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage, option
 
                 -   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
 
@@ -5439,7 +5524,7 @@ function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage, option
 
                 - 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))}
 
@@ -5453,11 +5538,30 @@ function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage, option
 /**
  * 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, '/');
 }
 
 /**