@promptbook/node 0.114.0-11 → 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-11';
+    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
@@ -2954,14 +2954,90 @@
      * without the generated script and the prompt it embeds.
      */
     const SCRIPT_EXECUTION_LOG_RAW_OUTPUT_MARKER = '--- raw output ---';
+    /**
+     * Command which terminates the Bash process tree rooted at the running harness.
+     *
+     * Bash's POSIX process IDs differ from Windows process IDs in Git Bash, so the Windows branch resolves the native PID
+     * before delegating to `taskkill`. Unix harnesses run in a dedicated Bash job process group, which can be terminated
+     * with its negative process ID.
+     */
+    const TERMINATE_BASH_PROCESS_TREE_COMMAND = process.platform === 'win32'
+        ? _spaceTrim.spaceTrim(`
+              HARNESS_WINDOWS_PROCESS_ID="$(ps -l -p "$HARNESS_PROCESS_ID" | awk 'NR == 2 { print $4 }')"
+              if [ -n "$HARNESS_WINDOWS_PROCESS_ID" ]; then
+                  MSYS_NO_PATHCONV=1 taskkill.exe /PID "$HARNESS_WINDOWS_PROCESS_ID" /T /F > /dev/null 2>&1 || true
+              fi
+          `)
+        : 'kill -TERM -- "-$HARNESS_PROCESS_ID" 2>/dev/null || true';
+    /**
+     * Shell condition that detects whether the Node process which owns the harness is still running.
+     *
+     * Git Bash translates process IDs and command switches, so querying the native Windows PID needs both `tasklist` and
+     * disabled MSYS path conversion there. Unix can use the native `kill -0` process existence check.
+     */
+    const IS_PARENT_PROCESS_RUNNING_CONDITION = process.platform === 'win32'
+        ? 'MSYS_NO_PATHCONV=1 tasklist.exe /FI "PID eq $PARENT_CODER_PROCESS_ID" /NH | awk -v processId="$PARENT_CODER_PROCESS_ID" \'$2 == processId { isFound = 1 } END { exit isFound ? 0 : 1 }\''
+        : 'kill -0 "$PARENT_CODER_PROCESS_ID" 2>/dev/null';
+    /**
+     * Environment variable that identifies the Node process responsible for a temporary harness shell.
+     */
+    const PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME = 'PTBK_CODER_PARENT_PROCESS_ID';
     /**
      * Small bash wrapper that preserves stdout/stderr streams while teeing both into the runtime log file.
+     *
+     * A watcher polls the owning Node process by its PID. If that process exits abruptly, the watcher stops the whole
+     * Bash and harness process tree instead of letting it continue as an orphan.
      */
     const LOGGED_BASH_WRAPPER_COMMAND = _spaceTrim.spaceTrim(`
+    PARENT_CODER_PROCESS_ID="\${${PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME}}"
+    unset ${PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME}
+
+    terminate_harness_process_tree() {
+        # Keep the EXIT cleanup intact so the wrapper can also stop its parent-process watcher.
+        trap - HUP INT TERM
+        ${TERMINATE_BASH_PROCESS_TREE_COMMAND}
+    }
+
+    is_parent_process_running() {
+        ${IS_PARENT_PROCESS_RUNNING_CONDITION}
+    }
+
     if [ -n "\${${PTBK_CODER_LOG_FILE_ENV_NAME}:-}" ]; then
-        exec > >(tee -a "\$${PTBK_CODER_LOG_FILE_ENV_NAME}") 2> >(tee -a "\$${PTBK_CODER_LOG_FILE_ENV_NAME}" >&2)
+        exec > >(tee -a "$${PTBK_CODER_LOG_FILE_ENV_NAME}") 2> >(tee -a "$${PTBK_CODER_LOG_FILE_ENV_NAME}" >&2)
+    fi
+
+    watch_parent_process() {
+        trap 'exit 0' HUP INT TERM
+
+        while is_parent_process_running; do
+            sleep 1
+        done
+
+        terminate_harness_process_tree
+    }
+
+    # Background harness jobs need their own process group on Unix so termination cannot reach the parent coder.
+    set -m
+    if ! is_parent_process_running; then
+        exit 1
     fi
-    bash "$1"
+    bash "$1" &
+    HARNESS_PROCESS_ID=$!
+
+    cleanup_parent_process_watcher() {
+        kill "$PARENT_PROCESS_WATCHER_PID" 2>/dev/null || true
+        wait "$PARENT_PROCESS_WATCHER_PID" 2>/dev/null || true
+    }
+
+    watch_parent_process &
+    PARENT_PROCESS_WATCHER_PID=$!
+
+    trap cleanup_parent_process_watcher EXIT
+    trap terminate_harness_process_tree HUP INT TERM
+
+    wait "$HARNESS_PROCESS_ID"
+    SCRIPT_EXIT_CODE=$?
+    exit "$SCRIPT_EXIT_CODE"
 `);
     /**
      * Shapes one bash invocation that optionally mirrors live script output into a temporary log file.
@@ -3017,6 +3093,38 @@
         return scriptPath.toLowerCase().endsWith('.test.sh') ? 'test shell' : 'runner shell';
     }
 
+    /**
+     * Standard streams used by every temporary Bash runner.
+     */
+    const BASH_PROCESS_STDIO = ['pipe', 'pipe', 'pipe'];
+    /**
+     * Whether the current Node process is running on Windows.
+     */
+    const IS_WINDOWS$1 = process.platform === 'win32';
+    /**
+     * Starts one temporary Bash script in a process tree owned by the current Node process.
+     *
+     * The wrapper watches the supplied owning process ID. When that process exits abruptly, the wrapper terminates every
+     * nested shell and harness process instead of leaving it orphaned.
+     *
+     * @private internal utility of the coding prompt runner
+     */
+    function $spawnLoggedBashScript(options) {
+        var _a;
+        const bashExecution = buildLoggedBashExecution(options.scriptPath, options.logPath);
+        const parentProcessId = (_a = options.parentProcessId) !== null && _a !== void 0 ? _a : process.pid;
+        return child_process.spawn('bash', bashExecution.args, {
+            detached: !IS_WINDOWS$1,
+            env: {
+                ...process.env,
+                ...bashExecution.env,
+                [PTBK_CODER_PARENT_PROCESS_ID_ENV_NAME]: parentProcessId.toString(),
+            },
+            stdio: BASH_PROCESS_STDIO,
+            windowsHide: true,
+        });
+    }
+
     /**
      * Prints one live shell output chunk to the terminal when console mirroring is enabled.
      */
@@ -3039,12 +3147,12 @@
     async function runBashScriptWithOutput(options) {
         var _a;
         await appendScriptExecutionLogStart(options);
-        const bashExecution = buildLoggedBashExecution(options.scriptPath, options.logPath);
         const scriptPathPosix = toPosixPath(options.scriptPath);
         const shouldPrintLiveOutput = (_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true;
         return await new Promise((resolve, reject) => {
-            const commandProcess = child_process.spawn('bash', bashExecution.args, {
-                env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+            const commandProcess = $spawnLoggedBashScript({
+                scriptPath: options.scriptPath,
+                logPath: options.logPath,
             });
             let output = '';
             let settled = false;
@@ -3103,8 +3211,9 @@
                 const failure = new Error(_spaceTrim.spaceTrim(output) || `Command "bash ${scriptPathPosix}" exited with code ${code}`);
                 settleWithLog(`failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`, () => reject(failure), failure);
             };
+            // Wait for `close`, not only `exit`, because the Bash wrapper can still be flushing its tee process
+            // substitutions after the direct shell exits.
             commandProcess.on('close', handleExit);
-            commandProcess.on('exit', handleExit);
             commandProcess.on('disconnect', () => {
                 const failure = new Error(`Command "bash ${scriptPathPosix}" disconnected`);
                 settleWithLog('failed after disconnect', () => reject(failure), failure);
@@ -3971,6 +4080,35 @@
             error.message.includes('bin/node'));
     }
 
+    /**
+     * Whether the current coder process runs on Windows.
+     */
+    const IS_WINDOWS = process.platform === 'win32';
+    /**
+     * Stops one active temporary Bash shell together with the harness process tree it owns.
+     *
+     * Unix sends `SIGTERM` to the wrapper so its shell trap terminates the separately grouped harness job. Windows does
+     * not reliably deliver that signal to Bash, so the native `taskkill` command terminates the direct shell tree instead.
+     *
+     * @private internal utility of the coding prompt runner
+     */
+    function $terminateLoggedBashProcessTree(commandProcess) {
+        if (commandProcess.exitCode !== null || commandProcess.signalCode !== null) {
+            return;
+        }
+        if (!IS_WINDOWS) {
+            commandProcess.kill('SIGTERM');
+            return;
+        }
+        if (!commandProcess.pid) {
+            return;
+        }
+        child_process.spawnSync('taskkill.exe', ['/PID', commandProcess.pid.toString(), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+    }
+
     /**
      * Maximum number of output characters included in thrown error messages.
      */
@@ -4013,15 +4151,16 @@
         const scriptPathPosix = toPosixPath(scriptPath);
         const shouldPrintLiveOutput = (_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true;
         await appendScriptExecutionLogStart(options);
-        const bashExecution = buildLoggedBashExecution(scriptPath, options.logPath);
         return await new Promise((resolve, reject) => {
-            const commandProcess = child_process.spawn('bash', bashExecution.args, {
-                env: bashExecution.env ? { ...process.env, ...bashExecution.env } : process.env,
+            const commandProcess = $spawnLoggedBashScript({
+                scriptPath,
+                logPath: options.logPath,
             });
             let stdoutBuffer = '';
             let stderrBuffer = '';
             let fullOutput = '';
             let markerSeen = false;
+            let isCompletedAfterIdleTimeout = false;
             let idleTimer;
             let settled = false;
             let isSettling = false;
@@ -4063,15 +4202,16 @@
                 });
             };
             /**
-             * Finishes a marker-completed run and then asks bash to stop.
+             * Stops a marker-completed process tree after its trailing output becomes idle.
              */
             const finishAfterIdleTimeout = () => {
-                settleWithLog('completed after idle timeout', () => resolve(fullOutput));
+                isCompletedAfterIdleTimeout = true;
+                idleTimer = undefined;
                 try {
-                    commandProcess.kill();
+                    $terminateLoggedBashProcessTree(commandProcess);
                 }
                 catch (_a) {
-                    // Windows can report EPERM when bash exits before the idle timer fires.
+                    // The close handler below still settles normally when Bash already exited before the idle timer fired.
                 }
             };
             /**
@@ -4130,7 +4270,11 @@
                 const failure = code === 0 || markerSeen
                     ? undefined
                     : new Error(buildCommandFailureMessage(scriptPathPosix, code, fullOutput));
-                const status = failure ? `failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}` : 'succeeded';
+                const status = isCompletedAfterIdleTimeout
+                    ? 'completed after idle timeout'
+                    : failure
+                        ? `failed with exit code ${code !== null && code !== void 0 ? code : 'unknown'}`
+                        : 'succeeded';
                 settleWithLog(status, () => {
                     if (!failure) {
                         resolve(fullOutput);
@@ -4139,8 +4283,9 @@
                     reject(failure);
                 });
             };
+            // Wait for `close`, not only `exit`, because the Bash wrapper can still be flushing its tee process
+            // substitutions after the direct shell exits.
             commandProcess.on('close', handleExit);
-            commandProcess.on('exit', handleExit);
             commandProcess.on('disconnect', () => {
                 const failure = new Error(buildCommandFailureMessage(scriptPathPosix, null, fullOutput));
                 settleWithLog('failed after disconnect', () => reject(failure), failure);
@@ -5093,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))}
@@ -5149,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;
     /**
-     * Title stored on every agent goal chat.
+     * 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;
+    /**
+     * 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
-
-        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.
+        return _spaceTrim.spaceTrim((block) => `
+            ## Planned goal-chat messages
 
-        - 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.
+            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.
 
-        Run the corresponding authenticated command:
+            ${block(buildCurrentPlannedMessagesLines(sidecar.currentPlannedMessages))}
 
-        \`\`\`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}"}'
+            Editing \`${sidecar.relativeSidecarPath}\` is the **only** way to change what wakes you. Writing in your answer that you scheduled something does not schedule anything.
 
-        # 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.
@@ -5236,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}
@@ -5255,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.
         `);
@@ -5263,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, '/');
     }
 
@@ -5276,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
 
@@ -5312,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))}
 
@@ -5326,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)}\``);
+        }
+        if (options.plannedMessagesSidecar) {
+            allowedFileChanges.push(`the \`commands\` array of \`${toPromptPath(options.plannedMessagesSidecar.relativeSidecarPath)}\``);
         }
-        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, '/')}\``;
+        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, '/');
     }
 
     /**
@@ -27345,6 +27594,30 @@
         }
     }
 
+    /**
+     * Pattern shared by Book parsing and editor highlighting for a commitment-like line.
+     *
+     * A Book commitment keyword consists of one or more all-uppercase words with at least
+     * two characters each. This deliberately mirrors the Book editor syntax rule so an
+     * unknown keyword starts a new source block everywhere it is interpreted.
+     *
+     * @private internal constant of `getBookCommitmentLineType`
+     */
+    const BOOK_COMMITMENT_LINE_TYPE_REGEX = /^\s*(?<type>[A-Z][A-Z0-9]+(?:\s+[A-Z][A-Z0-9]+)*)(?=\s|$)/;
+    /**
+     * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+     *
+     * @param line - One raw Book source line.
+     * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+     *
+     * @private internal utility of Book parsing and `<BookEditor/>`
+     */
+    function getBookCommitmentLineType(line) {
+        var _a;
+        const match = BOOK_COMMITMENT_LINE_TYPE_REGEX.exec(line);
+        return ((_a = match === null || match === void 0 ? void 0 : match.groups) === null || _a === void 0 ? void 0 : _a.type) || null;
+    }
+
     /**
      * Consumes the agent-name prelude from raw source.
      *
@@ -27402,13 +27675,15 @@
             return {
                 agentName: null,
                 commitments: [],
+                unknownCommitments: [],
                 nonCommitmentLines: [],
             };
         }
         const { lines, agentName, agentNameLineIndex, agentNameLineNumber } = parseAgentSourcePrelude(agentSource);
         const commitments = [];
+        const unknownCommitments = [];
         const nonCommitmentLines = agentNameLineIndex >= 0 ? [lines[agentNameLineIndex]] : [];
-        // Parse commitments with multiline support
+        // Parse commitments with multiline support.
         let currentCommitment = null;
         // Process lines starting from after the agent name line
         const startIndex = agentNameLineIndex >= 0 ? agentNameLineIndex + 1 : 0;
@@ -27422,25 +27697,11 @@
             // Check if this line starts or ends a code block
             if (trimmedLine.startsWith('```')) {
                 isInsideCodeBlock = !isInsideCodeBlock;
-                if (currentCommitment) {
-                    // If we are inside a commitment, the code block is part of it
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // If we are not inside a commitment, the code block is non-commitment
-                    nonCommitmentLines.push(line);
-                }
+                appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
                 continue;
             }
             if (isInsideCodeBlock) {
-                if (currentCommitment) {
-                    // If we are inside a commitment and a code block, the line is part of the commitment
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // If we are inside a code block but not a commitment, the line is non-commitment
-                    nonCommitmentLines.push(line);
-                }
+                appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
                 continue;
             }
             // Check if this line starts a new commitment
@@ -27449,22 +27710,14 @@
                 const typeRegex = definition.createTypeRegex();
                 const match = typeRegex.exec(line.trim());
                 if (match && ((_a = match.groups) === null || _a === void 0 ? void 0 : _a.type)) {
-                    // Save the previous commitment if it exists
-                    if (currentCommitment) {
-                        const fullContent = currentCommitment.contentLines.join('\n');
-                        commitments.push({
-                            type: currentCommitment.type,
-                            content: _spaceTrim.spaceTrim(fullContent),
-                            originalLine: currentCommitment.originalStartLine,
-                            lineNumber: currentCommitment.startLineNumber,
-                        });
-                    }
+                    appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
                     // Extract the initial content from the commitment line
                     const fullRegex = definition.createRegex();
                     const fullMatch = fullRegex.exec(line.trim());
                     const initialContent = ((_b = fullMatch === null || fullMatch === void 0 ? void 0 : fullMatch.groups) === null || _b === void 0 ? void 0 : _b.contents) || '';
                     // Start a new commitment
                     currentCommitment = {
+                        kind: 'known',
                         type: definition.type,
                         startLineNumber: i + 1,
                         originalStartLine: line,
@@ -27474,52 +27727,90 @@
                     break;
                 }
             }
+            if (foundNewCommitment) {
+                continue;
+            }
+            const unknownCommitmentType = getBookCommitmentLineType(line);
+            if (unknownCommitmentType) {
+                appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+                currentCommitment = {
+                    kind: 'unknown',
+                    type: unknownCommitmentType,
+                    startLineNumber: i + 1,
+                    originalStartLine: line,
+                    sourceLines: [line],
+                };
+                continue;
+            }
             // Check if this is a horizontal line (ends any current commitment)
             const isHorizontalLine = HORIZONTAL_LINE_PATTERN$1.test(line);
             if (isHorizontalLine) {
-                // Save the current commitment if it exists
-                if (currentCommitment) {
-                    const fullContent = currentCommitment.contentLines.join('\n');
-                    commitments.push({
-                        type: currentCommitment.type,
-                        content: _spaceTrim.spaceTrim(fullContent),
-                        originalLine: currentCommitment.originalStartLine,
-                        lineNumber: currentCommitment.startLineNumber,
-                    });
-                    currentCommitment = null;
-                }
+                appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
+                currentCommitment = null;
                 // Add horizontal line to non-commitment lines
                 nonCommitmentLines.push(line);
                 continue;
             }
-            if (!foundNewCommitment) {
-                if (currentCommitment) {
-                    // This line belongs to the current commitment
-                    currentCommitment.contentLines.push(line);
-                }
-                else {
-                    // This line is not part of any commitment
-                    nonCommitmentLines.push(line);
-                }
-            }
-        }
-        // Don't forget to save the last commitment if it exists
-        if (currentCommitment) {
-            const fullContent = currentCommitment.contentLines.join('\n');
-            commitments.push({
-                type: currentCommitment.type,
-                content: _spaceTrim.spaceTrim(fullContent),
-                originalLine: currentCommitment.originalStartLine,
-                lineNumber: currentCommitment.startLineNumber,
-            });
+            appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines);
         }
+        appendCurrentCommitment(currentCommitment, commitments, unknownCommitments);
         return {
             agentName,
             agentNameLineNumber,
             commitments,
+            unknownCommitments,
             nonCommitmentLines,
         };
     }
+    /**
+     * Stores the current known or unknown commitment in its appropriate parsed collection.
+     *
+     * @param currentCommitment - Commitment-like block collected so far.
+     * @param commitments - Parsed registered commitments to append to.
+     * @param unknownCommitments - Parsed unregistered commitments to append to.
+     *
+     * @private internal utility of `parseAgentSourceWithCommitments`
+     */
+    function appendCurrentCommitment(currentCommitment, commitments, unknownCommitments) {
+        if (!currentCommitment) {
+            return;
+        }
+        if (currentCommitment.kind === 'unknown') {
+            unknownCommitments.push({
+                type: currentCommitment.type,
+                originalLine: currentCommitment.originalStartLine,
+                lineNumber: currentCommitment.startLineNumber,
+                source: _spaceTrim.spaceTrim(currentCommitment.sourceLines.join('\n')),
+            });
+            return;
+        }
+        commitments.push({
+            type: currentCommitment.type,
+            content: _spaceTrim.spaceTrim(currentCommitment.contentLines.join('\n')),
+            originalLine: currentCommitment.originalStartLine,
+            lineNumber: currentCommitment.startLineNumber,
+        });
+    }
+    /**
+     * Adds one source line to the active commitment-like block, or to plain source content when none is active.
+     *
+     * @param currentCommitment - Commitment-like block currently being collected.
+     * @param line - Source line to append.
+     * @param nonCommitmentLines - Plain source lines to append to when no block is active.
+     *
+     * @private internal utility of `parseAgentSourceWithCommitments`
+     */
+    function appendLineToCurrentCommitmentOrNonCommitmentLines(currentCommitment, line, nonCommitmentLines) {
+        if (!currentCommitment) {
+            nonCommitmentLines.push(line);
+            return;
+        }
+        if (currentCommitment.kind === 'unknown') {
+            currentCommitment.sourceLines.push(line);
+            return;
+        }
+        currentCommitment.contentLines.push(line);
+    }
 
     /**
      * Plugin for importing agent books *(`.book` files)*
@@ -27657,7 +27948,8 @@
         requirements = await importReferencedFiles(requirements);
         requirements = appendMcpServers(requirements, agentSource);
         requirements = appendNonCommitmentContent(requirements, parseResult);
-        return appendExampleInteractions(requirements, parseResult);
+        requirements = appendExampleInteractions(requirements, parseResult);
+        return appendUnknownCommitmentContent(requirements, parseResult);
     }
     /**
      * Imports text files referenced by IMPORT commitments and appends their transformed content to the system message.
@@ -27779,6 +28071,36 @@
         }
         return appendSystemMessageSection(requirements, nonCommitmentContent);
     }
+    /**
+     * Appends unknown commitment blocks as final extra context without applying commitment side effects.
+     *
+     * @param requirements - Current requirements snapshot.
+     * @param parseResult - Parsed source including unknown commitment blocks.
+     * @returns Requirements with unknown commitment context appended at the end of the system message.
+     *
+     * @private internal utility of `augmentAgentModelRequirementsFromSource`
+     */
+    function appendUnknownCommitmentContent(requirements, parseResult) {
+        const unknownCommitmentContent = getUnknownCommitmentContent(parseResult);
+        if (!unknownCommitmentContent) {
+            return requirements;
+        }
+        return appendSystemMessageSection(requirements, unknownCommitmentContent);
+    }
+    /**
+     * Joins unknown commitment blocks into their final extra-context representation.
+     *
+     * @param parseResult - Parsed source including unknown commitment blocks.
+     * @returns Unknown commitment source blocks in their original order.
+     *
+     * @private internal utility of `appendUnknownCommitmentContent`
+     */
+    function getUnknownCommitmentContent(parseResult) {
+        return parseResult.unknownCommitments
+            .map((commitment) => commitment.source)
+            .filter(Boolean)
+            .join('\n\n');
+    }
     /**
      * Collects plain-text lines that were not parsed as commitments and should still become part of the final system message.
      *
@@ -39753,23 +40075,27 @@
     // TODO: [🧠][♿] Maybe export through `@promptbook/node`
 
     /**
-     * Attempts to locate the specified application on a Windows system by searching common installation directories.
+     * Attempts to locate the specified application on a Windows system by searching PATH and common installation directories.
      * Returns the path to the executable if found, or null otherwise.
      *
      * @private within the repository
      */
     async function locateAppOnWindows({ appName, windowsSuffix, }) {
         try {
-            const prefixes = [
+            const EXECUTABLE_FILENAME = windowsSuffix.replace(/^.*[\\/]/, '');
+            const PATH_EXECUTABLE_PATHS = (process.env.PATH || '')
+                .split(path.delimiter)
+                .filter(Boolean)
+                .map((pathPrefix) => path.join(pathPrefix, EXECUTABLE_FILENAME));
+            const INSTALLATION_EXECUTABLE_PATHS = [
                 process.env.LOCALAPPDATA,
                 path.join(process.env.LOCALAPPDATA || '', 'Programs'),
                 process.env.PROGRAMFILES,
                 process.env['PROGRAMFILES(X86)'],
-            ];
-            for (const prefix of prefixes) {
-                const path = prefix + windowsSuffix;
-                if (await isExecutable(path, $provideFilesystemForNode())) {
-                    return path;
+            ].map((pathPrefix) => pathPrefix + windowsSuffix);
+            for (const executablePath of [...PATH_EXECUTABLE_PATHS, ...INSTALLATION_EXECUTABLE_PATHS]) {
+                if (await isExecutable(executablePath, $provideFilesystemForNode())) {
+                    return executablePath;
                 }
             }
             throw new Error(`Can not locate app ${appName} on Windows.`);