@promptbook/cli 0.114.0-12 → 0.114.0-13

package/umd/index.umd.js

@@ -58,7 +58,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
@@ -4098,10 +4098,6 @@
      * Environment variable containing the internal worker token for local agent runners.
      */
     const PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN_ENV = 'PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN';
-    /**
-     * Header used by internal local-runner routes.
-     */
-    const USER_CHAT_WORKER_TOKEN_HEADER = 'x-user-chat-worker-token';
 
     /**
      * Format either small or big number
@@ -21892,7 +21888,7 @@
             return agentBookStats.isFile();
         }
         catch (error) {
-            if (isFileNotFoundError$6(error)) {
+            if (isFileNotFoundError$7(error)) {
                 return false;
             }
             throw error;
@@ -21901,7 +21897,7 @@
     /**
      * Returns true when one filesystem error indicates a missing path.
      */
-    function isFileNotFoundError$6(error) {
+    function isFileNotFoundError$7(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -21931,7 +21927,7 @@
             return await promises.readdir(queuedMessagesDirectoryPath, { withFileTypes: true });
         }
         catch (error) {
-            if (isFileNotFoundError$5(error)) {
+            if (isFileNotFoundError$6(error)) {
                 return [];
             }
             throw error;
@@ -21952,7 +21948,7 @@
     /**
      * Returns true when an error is a missing-path filesystem error.
      */
-    function isFileNotFoundError$5(error) {
+    function isFileNotFoundError$6(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -22430,7 +22426,7 @@
                 lastIndexLockState = await readGitIndexLockState(cwd, options.env);
                 if ((lastIndexLockState === null || lastIndexLockState === void 0 ? void 0 : lastIndexLockState.isStale) && !isStaleIndexLockRemoved) {
                     await promises.unlink(lastIndexLockState.path).catch((unlinkError) => {
-                        if (isFileNotFoundError$4(unlinkError)) {
+                        if (isFileNotFoundError$5(unlinkError)) {
                             return;
                         }
                         throw unlinkError;
@@ -22491,7 +22487,7 @@
             };
         }
         catch (error) {
-            if (isFileNotFoundError$4(error)) {
+            if (isFileNotFoundError$5(error)) {
                 return undefined;
             }
             throw error;
@@ -22548,7 +22544,7 @@
     /**
      * Detects missing-file errors while inspecting the lock file.
      */
-    function isFileNotFoundError$4(error) {
+    function isFileNotFoundError$5(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -29624,7 +29620,7 @@
             return crypto.createHash('sha1').update(content).digest('hex');
         }
         catch (error) {
-            if (isFileNotFoundError$3(error)) {
+            if (isFileNotFoundError$4(error)) {
                 return null;
             }
             throw error;
@@ -29639,7 +29635,7 @@
     /**
      * Returns true when an error is a missing-file filesystem error.
      */
-    function isFileNotFoundError$3(error) {
+    function isFileNotFoundError$4(error) {
         return Boolean(error &&
             typeof error === 'object' &&
             'code' in error &&
@@ -30632,7 +30628,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))}
@@ -30688,55 +30684,166 @@
     }
 
     /**
-     * Title stored on every agent goal chat.
+     * Milliseconds in one second.
+     *
+     * @private internal timeout-chat constant
+     */
+    const SECOND_IN_MILLISECONDS = 1000;
+    /**
+     * Seconds in one minute.
+     *
+     * @private internal timeout-chat constant
+     */
+    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;
+    /**
+     * Seconds in one day.
+     *
+     * @private internal timeout-chat constant
+     */
+    const DAY_IN_SECONDS = HOURS_IN_DAY * HOUR_IN_SECONDS;
+    /**
+     * 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
      */
+    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')}`;
+    }
     /**
-     * Internal endpoint used by managed coding agents to plan goal-chat messages.
+     * Formats one pluralized timeout unit.
+     *
+     * @private internal timeout-chat helper
      */
-    const AGENT_GOAL_CHAT_PLANNED_MESSAGES_INTERNAL_API_PATH = '/api/internal/agent-goal-chat-planned-messages';
+    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}"}'
+            -   **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:
 
-        # 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."}'
+            ${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}`;
+    }
 
-        # 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>"}'
-        \`\`\`
-    `);
+    /**
+     * Creates the stable file-system safe base name that belongs to one queued `.book` message.
+     *
+     * Every sidecar the Agents Server prepares next to a queued message (TEAM workspaces, planned-message
+     * files, ...) derives its own name from this one normalization, so a sidecar can always be found again
+     * from the message file name alone.
+     *
+     * @param messageFileName - File name of the queued message, with or without directories.
+     * @returns Normalized base name usable as a directory or file name.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentMessageSidecarBaseName(messageFileName) {
+        const rawBaseName = path.basename(messageFileName).replace(/\.book$/iu, '');
+        const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
+        return normalizedBaseName || 'message';
     }
 
     // Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
@@ -30770,9 +30877,7 @@
      * @private internal convention shared by the Agents Server and agent-folder runner
      */
     function createAgentTeamConversationWorkspaceDirectoryName(messageFileName) {
-        const rawBaseName = path.basename(messageFileName).replace(/\.book$/iu, '');
-        const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
-        return normalizedBaseName || 'message';
+        return createAgentMessageSidecarBaseName(messageFileName);
     }
     /**
      * Creates the relative active workspace path for one queued message.
@@ -30842,8 +30947,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}
@@ -30861,7 +30966,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.
         `);
@@ -30869,7 +30974,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, '/');
     }
 
@@ -30882,7 +30987,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
 
@@ -30918,7 +31023,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))}
 
@@ -30932,11 +31037,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 ${formatAllowedFileChanges(allowedFileChanges)}`;
+    }
+    /**
+     * Joins the allowed file-change phrases into one readable enumeration.
+     */
+    function formatAllowedFileChanges(allowedFileChanges) {
+        if (allowedFileChanges.length === 1) {
+            return allowedFileChanges[0];
         }
-        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 `${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, '/');
     }
 
     var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModels",description:"List of available model names together with their descriptions as JSON",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelsRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n```json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n```\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n```json\n{availableModels}\n```\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelsRequirements",format:"JSON",dependentParameterNames:["availableModels","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModels}` List of available model names together with their descriptions as JSON\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelsRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n\\`\\`\\`json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n\\`\\`\\`json\n{availableModels}\n\\`\\`\\`\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelsRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
@@ -37690,12 +37814,12 @@
         await promises.rm(finishedWorkspacePath, { recursive: true, force: true });
         await promises.mkdir(finishedWorkspacePath, { recursive: true });
         const relativePaths = [
-            toPortablePath$1(path.join(finishedRelativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME)),
+            toPortablePath$2(path.join(finishedRelativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME)),
         ];
         await promises.rename(activeManifestPath, path.join(finishedWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME));
         for (const transcriptFileName of transcriptFileNames) {
             await promises.rename(path.join(activeWorkspacePath, transcriptFileName), path.join(finishedWorkspacePath, transcriptFileName));
-            relativePaths.push(toPortablePath$1(path.join(finishedRelativeWorkspacePath, transcriptFileName)));
+            relativePaths.push(toPortablePath$2(path.join(finishedRelativeWorkspacePath, transcriptFileName)));
         }
         await promises.rm(activeWorkspacePath, { recursive: true, force: true });
         return { relativePaths };
@@ -37712,7 +37836,7 @@
                 .sort((firstFileName, secondFileName) => firstFileName.localeCompare(secondFileName));
         }
         catch (error) {
-            if (isFileNotFoundError$2(error)) {
+            if (isFileNotFoundError$3(error)) {
                 return [];
             }
             throw error;
@@ -37727,7 +37851,7 @@
             return true;
         }
         catch (error) {
-            if (isFileNotFoundError$2(error)) {
+            if (isFileNotFoundError$3(error)) {
                 return false;
             }
             throw error;
@@ -37736,11 +37860,204 @@
     /**
      * Converts a filesystem-relative path into a portable Git path.
      */
+    function toPortablePath$2(path) {
+        return path.replace(/\\/gu, '/');
+    }
+    /**
+     * Returns true when one filesystem error indicates a missing path.
+     */
+    function isFileNotFoundError$3(error) {
+        return Boolean(error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            (error.code === 'ENOENT' || error.code === 'ENOTDIR'));
+    }
+
+    // Note: [💞] This file defines the shared planned-message sidecar convention rather than one standalone entity.
+    /**
+     * Relative directory holding the planned-message sidecar of each queued message.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'planned');
+    /**
+     * Command actions an agent can request from its planned-message sidecar.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'cancel'];
+    /**
+     * Creates the relative planned-message sidecar path of one queued message.
+     *
+     * @param messageFileName - File name of the queued `.book` message.
+     * @returns Relative path of the sidecar inside the agent folder.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function createAgentPlannedMessagesSidecarPath(messageFileName) {
+        return path.join(AGENT_PLANNED_MESSAGES_DIRECTORY_PATH, `${createAgentMessageSidecarBaseName(messageFileName)}.json`);
+    }
+    /**
+     * Parses one untrusted planned-message sidecar written back by a coding harness.
+     *
+     * A malformed sidecar never fails the already answered chat, so this returns `null` instead of throwing.
+     *
+     * @param sidecarContent - Raw file content read from the agent folder.
+     * @returns Normalized sidecar, or `null` when it cannot be used.
+     *
+     * @private internal convention shared by the Agents Server and agent-folder runner
+     */
+    function parseAgentPlannedMessagesSidecar(sidecarContent) {
+        let parsedSidecar;
+        try {
+            parsedSidecar = JSON.parse(sidecarContent);
+        }
+        catch (_a) {
+            return null;
+        }
+        if (!parsedSidecar || typeof parsedSidecar !== 'object' || Array.isArray(parsedSidecar)) {
+            return null;
+        }
+        const sidecar = parsedSidecar;
+        if (sidecar.version !== 1 || typeof sidecar.agentPermanentId !== 'string') {
+            return null;
+        }
+        return {
+            version: 1,
+            agentPermanentId: sidecar.agentPermanentId,
+            currentPlannedMessages: normalizeAgentPlannedMessageSnapshots(sidecar.currentPlannedMessages),
+            commands: normalizeAgentPlannedMessageCommands(sidecar.commands),
+        };
+    }
+    /**
+     * Keeps only the commands whose action is understood by the planned-message actions.
+     *
+     * @param rawCommands - Untrusted `commands` value read from one sidecar.
+     * @returns Commands that can be dispatched, in their original order.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function normalizeAgentPlannedMessageCommands(rawCommands) {
+        if (!Array.isArray(rawCommands)) {
+            return [];
+        }
+        return rawCommands.filter(isAgentPlannedMessageCommand);
+    }
+    /**
+     * Checks whether one untrusted sidecar entry names a supported planned-message action.
+     *
+     * @param value - Untrusted command entry.
+     * @returns `true` when the entry can be dispatched.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function isAgentPlannedMessageCommand(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return false;
+        }
+        const action = value.action;
+        return (typeof action === 'string' &&
+            AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS.includes(action));
+    }
+    /**
+     * Keeps only the already planned messages that can be shown to the agent.
+     *
+     * @param rawSnapshots - Untrusted `currentPlannedMessages` value read from one sidecar.
+     * @returns Planned-message snapshots with the fields required for display and cancellation.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function normalizeAgentPlannedMessageSnapshots(rawSnapshots) {
+        if (!Array.isArray(rawSnapshots)) {
+            return [];
+        }
+        return rawSnapshots.filter(isAgentPlannedMessageSnapshot).map(createNormalizedAgentPlannedMessageSnapshot);
+    }
+    /**
+     * Normalizes the optional fields of one already planned message.
+     *
+     * @param snapshot - Planned-message entry with the required identity fields.
+     * @returns Snapshot with a usable repeat interval and message.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function createNormalizedAgentPlannedMessageSnapshot(snapshot) {
+        const intervalMs = Number(snapshot.intervalMs);
+        return {
+            timeoutId: snapshot.timeoutId,
+            dueAt: snapshot.dueAt,
+            message: typeof snapshot.message === 'string' ? snapshot.message : null,
+            intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? Math.floor(intervalMs) : null,
+        };
+    }
+    /**
+     * Checks whether one untrusted sidecar entry describes an already planned message.
+     *
+     * @param value - Untrusted planned-message entry.
+     * @returns `true` when the entry can be shown and cancelled.
+     *
+     * @private internal utility of `parseAgentPlannedMessagesSidecar`
+     */
+    function isAgentPlannedMessageSnapshot(value) {
+        return Boolean(value &&
+            typeof value === 'object' &&
+            typeof value.timeoutId === 'string' &&
+            typeof value.dueAt === 'string');
+    }
+
+    /**
+     * Loads the planned-message sidecar the Agents Server prepared for one queued message.
+     *
+     * @param projectPath - Absolute path of the current agent runner folder.
+     * @param queuedMessage - Queued message currently being answered.
+     * @returns Sidecar details for the prompt, or `null` outside Agents Server-managed runs.
+     */
+    async function loadAgentPlannedMessagesSidecar(projectPath, queuedMessage) {
+        const relativeSidecarPath = createAgentPlannedMessagesSidecarPath(queuedMessage.fileName);
+        const sidecarContent = await readOptionalTextFile$2(path.join(projectPath, relativeSidecarPath));
+        if (sidecarContent === null) {
+            return null;
+        }
+        const sidecar = parseAgentPlannedMessagesSidecar(sidecarContent);
+        if (!sidecar) {
+            return null;
+        }
+        return {
+            relativeSidecarPath: toPortablePath$1(relativeSidecarPath),
+            currentPlannedMessages: sidecar.currentPlannedMessages,
+        };
+    }
+    /**
+     * Reads one text file and treats a missing planned-message sidecar as absent.
+     *
+     * @param path - Absolute sidecar path.
+     * @returns File content, or `null` when the sidecar does not exist.
+     */
+    async function readOptionalTextFile$2(path) {
+        try {
+            return await promises.readFile(path, 'utf-8');
+        }
+        catch (error) {
+            if (isFileNotFoundError$2(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Converts a filesystem-relative path to the portable form used in prompts.
+     *
+     * @param path - Relative path inside the agent folder.
+     * @returns Path with forward slashes.
+     */
     function toPortablePath$1(path) {
         return path.replace(/\\/gu, '/');
     }
     /**
      * Returns true when one filesystem error indicates a missing path.
+     *
+     * @param error - Caught filesystem failure.
+     * @returns `true` for missing-path errors.
      */
     function isFileNotFoundError$2(error) {
         return Boolean(error &&
@@ -37755,7 +38072,7 @@
     async function loadAgentTeamConversationWorkspace(projectPath, queuedMessage) {
         const relativeWorkspacePath = createAgentTeamConversationWorkspacePath(queuedMessage.fileName);
         const manifestPath = path.join(projectPath, relativeWorkspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME);
-        const manifestContent = await readOptionalTextFile(manifestPath);
+        const manifestContent = await readOptionalTextFile$1(manifestPath);
         if (manifestContent === null) {
             return null;
         }
@@ -37783,7 +38100,7 @@
     /**
      * Reads one text file and treats a missing team workspace as absent.
      */
-    async function readOptionalTextFile(path) {
+    async function readOptionalTextFile$1(path) {
         try {
             return await promises.readFile(path, 'utf-8');
         }
@@ -37850,6 +38167,233 @@
         return `/agents/${encodeURIComponent(agentId)}/projects`;
     }
 
+    /**
+     * Parses every structured event out of one coding-harness runtime log.
+     *
+     * The local agent runner streams the answering harness output into a live runtime log file, one
+     * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+     * skipped so a partially written or interleaved log never breaks its consumers.
+     *
+     * @param logText - Raw runtime log content.
+     * @returns Structured events in the order they were streamed.
+     * @private internal utility of the agent-message runtime
+     */
+    function parseAgentMessageRuntimeLogEvents(logText) {
+        if (!logText) {
+            return [];
+        }
+        const events = [];
+        for (const line of logText.split(/\r?\n/u)) {
+            const event = parseAgentMessageRuntimeLogEvent(line);
+            if (event) {
+                events.push(event);
+            }
+        }
+        return events;
+    }
+    /**
+     * Parses one runtime log line into a structured event when it embeds JSON.
+     *
+     * @param line - One raw runtime log line.
+     * @returns Structured event, or `null` when the line carries no JSON object.
+     * @private internal helper of `parseAgentMessageRuntimeLogEvents`
+     */
+    function parseAgentMessageRuntimeLogEvent(line) {
+        const jsonStartIndex = line.indexOf('{');
+        if (jsonStartIndex === -1) {
+            return null;
+        }
+        try {
+            const parsedEvent = JSON.parse(line.slice(jsonStartIndex).trim());
+            if (typeof parsedEvent !== 'object' || parsedEvent === null || Array.isArray(parsedEvent)) {
+                return null;
+            }
+            return parsedEvent;
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+
+    /**
+     * Matches one project directory name following the agent `projects/` folder in a file path or command.
+     *
+     * Both path separators are accepted because the local runner answers messages on Unix and Windows,
+     * and JSON-encoded payloads escape backslashes.
+     *
+     * @private internal constant of agent-message touched projects
+     */
+    const TOUCHED_PROJECT_PATH_REGEX = new RegExp(`${AGENT_PROJECTS_DIRECTORY_PATH}[\\\\/]+([^\\\\/"'\\s,;:]+)`, 'giu');
+    /**
+     * Resolves which projects one coding harness touched while answering a single message.
+     *
+     * The runtime log streams what the harness really did, so a project counts as touched when the
+     * harness named it in a tool invocation — reading, searching, running, or editing files inside
+     * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+     * narration are ignored so a project merely mentioned in the conversation is never reported.
+     *
+     * Every candidate is matched against the projects that really exist, which both filters prompt
+     * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+     *
+     * @param options - Raw runtime log content and the project directory names of the agent.
+     * @returns Touched project names in the canonical spelling, ordered by first appearance.
+     * @private internal utility of the agent-message runtime
+     */
+    function resolveAgentMessageTouchedProjectNames(options) {
+        const canonicalProjectNames = createCanonicalProjectNameLookup(options.knownProjectNames);
+        if (canonicalProjectNames.size === 0) {
+            return [];
+        }
+        const touchedProjectNames = new Set();
+        for (const event of parseAgentMessageRuntimeLogEvents(options.logText)) {
+            for (const toolInvocationText of resolveRuntimeLogEventToolInvocationTexts(event)) {
+                for (const candidateProjectName of resolveCandidateProjectNames(toolInvocationText)) {
+                    const canonicalProjectName = canonicalProjectNames.get(candidateProjectName.toLowerCase());
+                    if (canonicalProjectName !== undefined) {
+                        touchedProjectNames.add(canonicalProjectName);
+                    }
+                }
+            }
+        }
+        return Array.from(touchedProjectNames);
+    }
+    /**
+     * Indexes the existing project directory names by their lower-cased form.
+     *
+     * @param knownProjectNames - Project directory names of the agent.
+     * @returns Lookup from the lower-cased name to its canonical spelling.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function createCanonicalProjectNameLookup(knownProjectNames) {
+        const canonicalProjectNames = new Map();
+        for (const knownProjectName of knownProjectNames) {
+            const normalizedProjectName = knownProjectName.trim();
+            if (normalizedProjectName.length > 0) {
+                canonicalProjectNames.set(normalizedProjectName.toLowerCase(), normalizedProjectName);
+            }
+        }
+        return canonicalProjectNames;
+    }
+    /**
+     * Collects the texts of every tool invocation described by one runtime log event.
+     *
+     * Claude Code reports tool invocations as `tool_use` content blocks, while Codex reports executed
+     * commands and file changes as items — both carry the paths the harness worked with.
+     *
+     * @param event - One structured runtime log event.
+     * @returns Texts that may contain project paths.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function resolveRuntimeLogEventToolInvocationTexts(event) {
+        var _a, _b, _c;
+        const toolInvocationTexts = [];
+        for (const contentBlock of ((_a = event.message) === null || _a === void 0 ? void 0 : _a.content) || []) {
+            if (contentBlock.type === 'tool_use' && contentBlock.input) {
+                toolInvocationTexts.push(serializeToolInput(contentBlock.input));
+            }
+        }
+        if (typeof ((_b = event.item) === null || _b === void 0 ? void 0 : _b.command) === 'string') {
+            toolInvocationTexts.push(event.item.command);
+        }
+        for (const fileChange of ((_c = event.item) === null || _c === void 0 ? void 0 : _c.changes) || []) {
+            if (typeof fileChange.path === 'string') {
+                toolInvocationTexts.push(fileChange.path);
+            }
+        }
+        return toolInvocationTexts;
+    }
+    /**
+     * Serializes one tool input payload into scannable text.
+     *
+     * @param toolInput - Tool arguments of one harness tool invocation.
+     * @returns Serialized payload, or an empty string when it cannot be serialized.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function serializeToolInput(toolInput) {
+        try {
+            return JSON.stringify(toolInput);
+        }
+        catch (_a) {
+            return '';
+        }
+    }
+    /**
+     * Extracts every project directory name mentioned right after the agent `projects/` folder.
+     *
+     * @param toolInvocationText - One tool payload, command, or changed path.
+     * @returns Candidate project directory names.
+     * @private internal helper of `resolveAgentMessageTouchedProjectNames`
+     */
+    function resolveCandidateProjectNames(toolInvocationText) {
+        const candidateProjectNames = [];
+        const projectPathRegex = new RegExp(TOUCHED_PROJECT_PATH_REGEX.source, TOUCHED_PROJECT_PATH_REGEX.flags);
+        let projectPathMatch = projectPathRegex.exec(toolInvocationText);
+        while (projectPathMatch !== null) {
+            const candidateProjectName = projectPathMatch[1];
+            if (candidateProjectName) {
+                candidateProjectNames.push(candidateProjectName);
+            }
+            projectPathMatch = projectPathRegex.exec(toolInvocationText);
+        }
+        return candidateProjectNames;
+    }
+
+    /**
+     * Resolves which agent projects one answered message viewed or edited.
+     *
+     * The runtime log is deleted as soon as the harness run finishes, so this must be called while
+     * the log still exists — the Agents Server later shows the reported projects as chips below the
+     * answer. Reporting touched projects is best-effort telemetry: an unreadable log or projects
+     * folder simply yields no projects instead of failing the already answered message.
+     *
+     * @param options - Agent folder path and the live runtime log path of the answered message.
+     * @returns Touched project directory names, ordered by first appearance in the run.
+     */
+    async function resolveTouchedAgentProjects(options) {
+        const [logText, knownProjectNames] = await Promise.all([
+            readOptionalTextFile(options.runtimeLogPath),
+            listAgentProjectDirectoryNames(options.projectPath),
+        ]);
+        return resolveAgentMessageTouchedProjectNames({ logText, knownProjectNames });
+    }
+    /**
+     * Lists the direct project directories of one agent folder.
+     *
+     * @param projectPath - Absolute path of the local agent folder.
+     * @returns Project directory names, or an empty list when the agent has no projects folder.
+     *
+     * @private helper of `resolveTouchedAgentProjects`
+     */
+    async function listAgentProjectDirectoryNames(projectPath) {
+        try {
+            const projectsRootEntries = await promises.readdir(path.join(projectPath, AGENT_PROJECTS_DIRECTORY_PATH), {
+                withFileTypes: true,
+            });
+            return projectsRootEntries
+                .filter((projectsRootEntry) => projectsRootEntry.isDirectory())
+                .map((projectDirectoryEntry) => projectDirectoryEntry.name);
+        }
+        catch (_a) {
+            return [];
+        }
+    }
+    /**
+     * Reads one text file and treats a missing runtime log as "nothing was recorded".
+     *
+     * @param filePath - Absolute path of the file to read.
+     * @returns File content, or `null` when it cannot be read.
+     *
+     * @private helper of `resolveTouchedAgentProjects`
+     */
+    async function readOptionalTextFile(filePath) {
+        try {
+            return await promises.readFile(filePath, 'utf-8');
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+
     // Note: [💞] Ignore a discrepancy between file name and entity name
     /**
      * File suffix appended to one answered message book to store its run report sidecar.
@@ -38129,10 +38673,11 @@
         const { projectPath, options: runOptions, runner, actualRunnerModel, queuedMessage, uiHandle, isSharedDashboard, } = options;
         const agentSystemMessage = await loadLocalAgentSystemMessage(projectPath);
         const teamWorkspace = await loadAgentTeamConversationWorkspace(projectPath, queuedMessage);
+        const plannedMessagesSidecar = await loadAgentPlannedMessagesSidecar(projectPath, queuedMessage);
         const agentServerRuntimeApi = resolveAgentProjectRuntimePromptApi(projectPath);
         const prompt = buildAgentMessagePrompt(queuedMessage.relativePath, agentSystemMessage, {
             projectRuntimeApi: agentServerRuntimeApi,
-            goalChatRuntimeApi: agentServerRuntimeApi,
+            plannedMessagesSidecar: plannedMessagesSidecar || undefined,
             projectsUrlPath: resolveAgentProjectsUrlPath(projectPath),
             teamWorkspace: teamWorkspace || undefined,
         });
@@ -38153,21 +38698,29 @@
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setCurrentScriptPath(scriptPath);
         }
         uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.startCapturingAgentOutput();
+        const executionStartedAt = new Date().toISOString();
         let promptRunResult;
+        let touchedProjectNames = [];
         try {
             try {
-                promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => await runPromptWithTestFeedback({
-                    runner,
-                    prompt,
-                    scriptPath,
-                    projectPath,
-                    promptLabel: queuedMessage.relativePath,
-                    logPath,
-                    preserveArtifactsOnSuccess: false,
-                    onAttemptStarted: (attemptCount) => {
-                        uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(attemptCount);
-                    },
-                }), { preserveArtifactsOnSuccess: false });
+                promptRunResult = await withPromptRuntimeLog(scriptPath, async (logPath) => {
+                    const runResult = await runPromptWithTestFeedback({
+                        runner,
+                        prompt,
+                        scriptPath,
+                        projectPath,
+                        promptLabel: queuedMessage.relativePath,
+                        logPath,
+                        preserveArtifactsOnSuccess: false,
+                        onAttemptStarted: (attemptCount) => {
+                            uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.state.setAttempt(attemptCount);
+                        },
+                    });
+                    // Note: The runtime log is deleted right after this handler, so the projects this
+                    //       answer worked with must be resolved while the log still exists.
+                    touchedProjectNames = await resolveTouchedAgentProjects({ projectPath, runtimeLogPath: logPath });
+                    return runResult;
+                }, { preserveArtifactsOnSuccess: false });
             }
             catch (error) {
                 throw withAgentWatchErrorContext(error, {
@@ -38181,6 +38734,7 @@
         finally {
             uiHandle === null || uiHandle === void 0 ? void 0 : uiHandle.stopCapturingAgentOutput();
         }
+        const executionFinishedAt = new Date().toISOString();
         await normalizeLineEndingsForAgentRound(projectPath, runOptions, roundChangedFilesSnapshot);
         const finishedTeamWorkspace = await finalizeAgentTeamConversationWorkspace({
             projectPath,
@@ -38199,6 +38753,11 @@
                 modelName: actualRunnerModel,
                 loginMethod: promptRunResult.loginMethod,
                 usage: promptRunResult.usage,
+                executionTiming: {
+                    startedAt: executionStartedAt,
+                    finishedAt: executionFinishedAt,
+                },
+                ...(touchedProjectNames.length === 0 ? {} : { touchedProjectNames }),
             },
         });
         await commitAnsweredMessageIfEnabled({