@promptbook/node 0.113.0-9 → 0.114.0-0

package/umd/index.umd.js

@@ -51,7 +51,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-9';
+    const PROMPTBOOK_ENGINE_VERSION = '0.114.0-0';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -88,6 +88,15 @@
      * @public exported from `@promptbook/node`
      */
     const AGENT_FAILED_MESSAGES_DIRECTORY_PATH = path.join(AGENT_MESSAGES_DIRECTORY_PATH, 'failed');
+    /**
+     * Relative path to the agent-owned projects root used by the agent folder convention.
+     *
+     * Each direct child directory is one project — an isolated folder the agent fully controls
+     * (files, scripts, optionally its own git repository).
+     *
+     * @private internal constant of the agent folder convention, used by agent runners and the Agents Server
+     */
+    const AGENT_PROJECTS_DIRECTORY_PATH = 'projects';
 
     /**
      * Parser for the agent source for Promptbook agents in book language
@@ -484,48 +493,6 @@
         }
     }
 
-    /**
-     * Orders JSON object by keys
-     *
-     * @returns The same type of object as the input re-ordered
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function orderJson(options) {
-        const { value, order } = options;
-        const orderedValue = {
-            ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
-            ...value,
-        };
-        return orderedValue;
-    }
-
-    /**
-     * Freezes the given object and all its nested objects recursively
-     *
-     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
-     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
-     *
-     * @returns The same object as the input, but deeply frozen
-     *
-     * @public exported from `@promptbook/utils`
-     */
-    function $deepFreeze(objectValue) {
-        if (Array.isArray(objectValue)) {
-            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
-        }
-        const propertyNames = Object.getOwnPropertyNames(objectValue);
-        for (const propertyName of propertyNames) {
-            const value = objectValue[propertyName];
-            if (value && typeof value === 'object') {
-                $deepFreeze(value);
-            }
-        }
-        Object.freeze(objectValue);
-        return objectValue;
-    }
-    // TODO: [🧠] Is there a way how to meaningfully test this utility
-
     /**
      * Class implementing take chain.
      *
@@ -1830,6 +1797,110 @@
         }
     }
 
+    /**
+     * Single source of truth about how each supported CLI coding harness is installed and detected.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    const HARNESS_DEFINITIONS = {
+        'openai-codex': {
+            harnessName: 'openai-codex',
+            label: 'OpenAI Codex',
+            commandName: 'codex',
+            npmPackageName: '@openai/codex',
+        },
+        'github-copilot': {
+            harnessName: 'github-copilot',
+            label: 'GitHub Copilot',
+            commandName: 'copilot',
+            npmPackageName: '@github/copilot',
+            // Note: The GitHub Copilot CLI downloads its native binary in a postinstall script
+            npmInstallEnvironment: { npm_config_ignore_scripts: 'false' },
+        },
+        cline: {
+            harnessName: 'cline',
+            label: 'Cline',
+            commandName: 'cline',
+            npmPackageName: 'cline',
+        },
+        'claude-code': {
+            harnessName: 'claude-code',
+            label: 'Claude Code',
+            commandName: 'claude',
+            npmPackageName: '@anthropic-ai/claude-code',
+        },
+        opencode: {
+            harnessName: 'opencode',
+            label: 'Opencode',
+            commandName: 'opencode',
+            npmPackageName: 'opencode-ai',
+        },
+        gemini: {
+            harnessName: 'gemini',
+            label: 'Gemini CLI',
+            commandName: 'gemini',
+            npmPackageName: '@google/gemini-cli',
+        },
+    };
+    /**
+     * Looks up the definition of one supported CLI coding harness.
+     *
+     * @private internal utility of `promptbookCli`
+     */
+    function getHarnessDefinition(harnessName) {
+        const definition = HARNESS_DEFINITIONS[harnessName];
+        if (definition === undefined) {
+            throw new UnexpectedError(_spaceTrim.spaceTrim(`
+                Missing harness definition for \`${harnessName}\`.
+
+                Every harness must be described in \`HARNESS_DEFINITIONS\`.
+            `));
+        }
+        return definition;
+    }
+
+    /**
+     * Orders JSON object by keys
+     *
+     * @returns The same type of object as the input re-ordered
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function orderJson(options) {
+        const { value, order } = options;
+        const orderedValue = {
+            ...(order === undefined ? {} : Object.fromEntries(order.map((key) => [key, undefined]))),
+            ...value,
+        };
+        return orderedValue;
+    }
+
+    /**
+     * Freezes the given object and all its nested objects recursively
+     *
+     * Note: `$` is used to indicate that this function is not a pure function - it mutates given object
+     * Note: This function mutates the object and returns the original (but mutated-deep-freezed) object
+     *
+     * @returns The same object as the input, but deeply frozen
+     *
+     * @public exported from `@promptbook/utils`
+     */
+    function $deepFreeze(objectValue) {
+        if (Array.isArray(objectValue)) {
+            return Object.freeze(objectValue.map((item) => $deepFreeze(item)));
+        }
+        const propertyNames = Object.getOwnPropertyNames(objectValue);
+        for (const propertyName of propertyNames) {
+            const value = objectValue[propertyName];
+            if (value && typeof value === 'object') {
+                $deepFreeze(value);
+            }
+        }
+        Object.freeze(objectValue);
+        return objectValue;
+    }
+    // TODO: [🧠] Is there a way how to meaningfully test this utility
+
     /**
      * This error type indicates that somewhere in the code non-Error object was thrown and it was wrapped into the `WrappedError`
      *
@@ -3076,6 +3147,55 @@
         });
     }
 
+    /**
+     * Minimum timer duration used to avoid a zero-millisecond polling loop.
+     */
+    const MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS = 1;
+    /**
+     * Waits until one wall-clock deadline has passed.
+     *
+     * The remaining time is recalculated from `Date.now()` after every poll and after every tick callback.
+     * This makes waits elapse while the process is paused at a checkpoint or the computer is asleep.
+     *
+     * @private internal utility of `ptbk coder` wait handling
+     */
+    async function waitUntilWorldTimeDeadline(options) {
+        var _a;
+        const { deadlineTimeMs, pollIntervalMs, onTick, shouldStopWaiting } = options;
+        const normalizedPollIntervalMs = Math.max(MINIMUM_WORLD_TIME_WAIT_POLL_INTERVAL_MS, pollIntervalMs);
+        const waitForMilliseconds = (_a = options.waitForMilliseconds) !== null && _a !== void 0 ? _a : waitForRegularMilliseconds;
+        while (true) {
+            if (shouldStopWaiting === null || shouldStopWaiting === void 0 ? void 0 : shouldStopWaiting()) {
+                return;
+            }
+            const remainingDurationMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationMs <= 0) {
+                return;
+            }
+            await (onTick === null || onTick === void 0 ? void 0 : onTick(remainingDurationMs));
+            if (shouldStopWaiting === null || shouldStopWaiting === void 0 ? void 0 : shouldStopWaiting()) {
+                return;
+            }
+            const remainingDurationAfterTickMs = getRemainingDurationMs(deadlineTimeMs);
+            if (remainingDurationAfterTickMs <= 0) {
+                return;
+            }
+            await waitForMilliseconds(Math.min(normalizedPollIntervalMs, remainingDurationAfterTickMs));
+        }
+    }
+    /**
+     * Returns the remaining wall-clock duration until a timestamp.
+     */
+    function getRemainingDurationMs(deadlineTimeMs) {
+        return Math.max(0, deadlineTimeMs - Date.now());
+    }
+    /**
+     * Waits for one short polling interval.
+     */
+    async function waitForRegularMilliseconds(durationMs) {
+        await new Promise((resolve) => setTimeout(resolve, durationMs));
+    }
+
     /**
      * Base delimiter used for passing large prompts through stdin.
      */
@@ -3485,36 +3605,32 @@
      * Waits until the Claude Code session can be resumed, keeping terminal status clear.
      */
     async function waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options) {
-        var _a, _b, _c;
+        var _a, _b;
         const delayMs = getClaudeCodeSessionLimitDelayMs(sessionLimit);
+        const resetDeadlineTimeMs = Date.now() + delayMs;
         const sessionLabel = formatClaudeCodeSessionIdForDisplay(sessionLimit.sessionId);
         const resetSummary = formatClaudeCodeSessionLimitForDisplay(sessionLimit);
         if ((_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true) {
             console.warn(colors__default["default"].yellow(`[claude-code] Session limit detected for ${sessionLimit.sessionId}. Resurrection #${resurrectionCount} will resume with --resume after ${formatDurationMs(delayMs)}. ${resetSummary}`));
         }
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
-                checkpointLabel: 'the Claude Code session limit reset',
-                phase: 'waiting',
-                statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(remainingDelayMs)}`,
-            }));
-            const currentDelayMs = Math.min(CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS, remainingDelayMs);
-            await waitFor$1(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
-        await ((_c = options.waitForPauseCheckpoint) === null || _c === void 0 ? void 0 : _c.call(options, {
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: resetDeadlineTimeMs,
+            pollIntervalMs: CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
+                    checkpointLabel: 'the Claude Code session limit reset',
+                    phase: 'waiting',
+                    statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(Math.min(remainingDelayMs, delayMs))}`,
+                }));
+            },
+        });
+        await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
             checkpointLabel: 'resurrecting the Claude Code session with --resume',
             phase: 'running',
             statusMessage: `Resurrecting Claude Code session ${sessionLabel} with --resume`,
         }));
     }
-    /**
-     * Waits for a fixed amount of milliseconds.
-     */
-    async function waitFor$1(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a Claude Code session id for compact terminal status lines.
      */
@@ -4122,6 +4238,27 @@
         }
     }
 
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+    /**
+     * Stable stdout marker printed by the generated Codex runner script to report which login method it used.
+     *
+     * The marker is followed by the resolved method keyword, for example `ptbk-codex-login-method: chatgpt`,
+     * so `parseCodexLoginMethodFromOutput` can recover it from the captured runner output.
+     *
+     * @private internal constant of the OpenAI Codex runner
+     */
+    const CODEX_LOGIN_METHOD_MARKER = 'ptbk-codex-login-method:';
+    /**
+     * Substring that the `codex login status` command prints when the Codex CLI is signed in with a
+     * ChatGPT subscription account instead of an `OPENAI_API_KEY`.
+     *
+     * This is the single source of truth for detecting an active ChatGPT login, reused by the Codex runner
+     * script and by the Agents Server harness authentication status resolver.
+     *
+     * @private internal constant of the OpenAI Codex runner and the Agents Server Harness Auth
+     */
+    const CODEX_CHATGPT_LOGIN_STATUS_NEEDLE = 'Logged in using ChatGPT';
+
     /**
      * Default Codex reasoning effort preserved for backwards compatibility when no CLI override is provided.
      */
@@ -4138,10 +4275,28 @@
         const delimiter = resolveShellHereDocumentDelimiter(CODEX_PROMPT_DELIMITER, options.prompt);
         const projectPath = toPosixPath(options.projectPath);
         const loginMethodConfig = spaceTrim(`
+        CODEX_LOGIN_STATUS="$(
+            unset OPENAI_API_KEY OPENAI_BASE_URL CODEX_API_KEY
+            # 'codex login status' prints the "Logged in using ChatGPT" line to stderr, so merge stderr into stdout (2>&1) to capture it
+            ${options.codexCommand} login status 2>&1 || true
+        )"
+        case "$CODEX_LOGIN_STATUS" in
+            *"${CODEX_CHATGPT_LOGIN_STATUS_NEEDLE}"*)
+                IS_CODEX_CHATGPT_LOGIN_ACTIVE=1
+                ;;
+            *)
+                IS_CODEX_CHATGPT_LOGIN_ACTIVE=0
+                ;;
+        esac
+
+        CODEX_LOGIN_METHOD=chatgpt
         ${options.allowCredits ? 'CODEX_LOGIN_METHOD_ARGUMENTS=()' : 'CODEX_LOGIN_METHOD_ARGUMENTS=(-c forced_login_method=chatgpt)'}
         unset CODEX_API_KEY
-        if [ "\${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" = "1" ] && [ -n "\${OPENAI_API_KEY:-}" ]; then
+        if [ "$IS_CODEX_CHATGPT_LOGIN_ACTIVE" != "1" ] &&
+            [ "\${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" = "1" ] &&
+            [ -n "\${OPENAI_API_KEY:-}" ]; then
             CODEX_LOGIN_METHOD_ARGUMENTS=(-c forced_login_method=api)
+            CODEX_LOGIN_METHOD=api
             CODEX_API_KEY="\${OPENAI_API_KEY}"
             export CODEX_API_KEY
         fi
@@ -4160,11 +4315,15 @@
             '',
             loginMethodConfig,
             '',
-            'if [ "${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" != "1" ] || [ -z "${OPENAI_API_KEY:-}" ]; then',
+            'if [ "$IS_CODEX_CHATGPT_LOGIN_ACTIVE" = "1" ] ||',
+            '    [ "${PTBK_OPENAI_CODEX_USE_API_KEY:-0}" != "1" ] ||',
+            '    [ -z "${OPENAI_API_KEY:-}" ]; then',
             'unset OPENAI_API_KEY',
             'unset OPENAI_BASE_URL',
             'fi',
             '',
+            `printf '%s %s\\n' '${CODEX_LOGIN_METHOD_MARKER}' "\${CODEX_LOGIN_METHOD}"`,
+            '',
             `${options.codexCommand} \\`,
             '    "${CODEX_LOGIN_METHOD_ARGUMENTS[@]}" \\',
             `    -c model_reasoning_effort="${thinkingLevel}" \\`,
@@ -4366,6 +4525,37 @@
         return (_c = OPENAI_MODELS.find((model) => model.modelName === CODEX_FALLBACK_PRICING_MODEL)) === null || _c === void 0 ? void 0 : _c.pricing;
     }
 
+    /**
+     * Detects which login method Codex used from the captured CLI output.
+     *
+     * The generated Codex runner script prints one `CODEX_LOGIN_METHOD_MARKER` line before invoking Codex.
+     * The most recent marker wins so retries within one captured output resolve to the final decision.
+     *
+     * @returns The resolved login method, or `unknown` when no marker is present.
+     */
+    function parseCodexLoginMethodFromOutput(output) {
+        const lines = output.split(/\r?\n/);
+        for (let index = lines.length - 1; index >= 0; index--) {
+            const line = lines[index];
+            if (line === undefined) {
+                continue;
+            }
+            const markerIndex = line.indexOf(CODEX_LOGIN_METHOD_MARKER);
+            if (markerIndex === -1) {
+                continue;
+            }
+            const reportedMethod = line.slice(markerIndex + CODEX_LOGIN_METHOD_MARKER.length).trim().toLowerCase();
+            if (reportedMethod === 'chatgpt') {
+                return 'chatgpt';
+            }
+            if (reportedMethod === 'api') {
+                return 'api';
+            }
+            return 'unknown';
+        }
+        return 'unknown';
+    }
+
     /**
      * Error signatures that mean Codex requires credit spending to continue.
      */
@@ -4475,12 +4665,6 @@
      * Randomized delay proportion added/subtracted for retry jitter.
      */
     const RATE_LIMIT_BACKOFF_JITTER_RATIO = 0.15;
-    /**
-     * Waits for one given amount of milliseconds.
-     */
-    async function waitFor(delayMs) {
-        await new Promise((resolve) => setTimeout(resolve, delayMs));
-    }
     /**
      * Formats a delay value into a concise `xh ym zs` style label.
      */
@@ -4558,7 +4742,10 @@
                         preserveArtifactsOnSuccess: options.preserveArtifactsOnSuccess,
                     });
                     this.rateLimitBackoff.reset();
-                    return { usage: buildCodexUsageFromOutput(output, this.options.model) };
+                    return {
+                        usage: buildCodexUsageFromOutput(output, this.options.model),
+                        loginMethod: parseCodexLoginMethodFromOutput(output),
+                    };
                 }
                 catch (error) {
                     const details = extractCodexFailureDetails(error);
@@ -4570,13 +4757,18 @@
                         throw error;
                     }
                     const delayMs = this.rateLimitBackoff.nextDelayMs();
-                    const retryAt = new Date(Date.now() + delayMs).toISOString();
+                    const retryDeadlineTimeMs = Date.now() + delayMs;
+                    const retryAt = new Date(retryDeadlineTimeMs).toISOString();
                     const retryIndex = this.rateLimitBackoff.retryCount;
                     const summary = extractFailureSummary(details);
                     if ((_b = options.shouldPrintLiveOutput) !== null && _b !== void 0 ? _b : true) {
                         console.warn(colors__default["default"].yellow(`[codex] Rate limit/quota detected (${summary}). Retry #${retryIndex} in ${formatDelay(delayMs)} at ${retryAt}.`));
                     }
-                    await waitForRetryDelay(delayMs, options);
+                    await waitForRetryDelay({
+                        delayMs,
+                        retryDeadlineTimeMs,
+                        promptRunOptions: options,
+                    });
                 }
             }
         }
@@ -4584,20 +4776,21 @@
     /**
      * Waits for the next Codex retry while polling for requested pause checkpoints.
      */
-    async function waitForRetryDelay(delayMs, options) {
-        var _a;
-        let remainingDelayMs = delayMs;
-        while (remainingDelayMs > 0) {
-            const remainingDelayLabel = formatDelay(remainingDelayMs);
-            await ((_a = options.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(options, {
-                checkpointLabel: 'the next OpenAI Codex retry after rate limit',
-                phase: 'running',
-                statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
-            }));
-            const currentDelayMs = Math.min(RATE_LIMIT_BACKOFF_POLL_MS, remainingDelayMs);
-            await waitFor(currentDelayMs);
-            remainingDelayMs -= currentDelayMs;
-        }
+    async function waitForRetryDelay(options) {
+        const { delayMs, retryDeadlineTimeMs, promptRunOptions } = options;
+        await waitUntilWorldTimeDeadline({
+            deadlineTimeMs: retryDeadlineTimeMs,
+            pollIntervalMs: RATE_LIMIT_BACKOFF_POLL_MS,
+            onTick: async (remainingDelayMs) => {
+                var _a;
+                const remainingDelayLabel = formatDelay(Math.min(remainingDelayMs, delayMs));
+                await ((_a = promptRunOptions.waitForPauseCheckpoint) === null || _a === void 0 ? void 0 : _a.call(promptRunOptions, {
+                    checkpointLabel: 'the next OpenAI Codex retry after rate limit',
+                    phase: 'running',
+                    statusMessage: `Waiting ${remainingDelayLabel} before retrying OpenAI Codex`,
+                }));
+            },
+        });
     }
 
     /**
@@ -4735,17 +4928,6 @@
      * Constant for cline model.
      */
     const CLINE_MODEL = 'gemini:gemini-3-flash-preview';
-    /**
-     * Map of runner labels.
-     */
-    const RUNNER_LABELS = {
-        'openai-codex': 'OpenAI Codex',
-        'github-copilot': 'GitHub Copilot',
-        cline: 'Cline',
-        'claude-code': 'Claude Code',
-        opencode: 'Opencode',
-        gemini: 'Gemini CLI',
-    };
     /**
      * Resolves the configured prompt runner together with status-line metadata.
      *
@@ -4837,8 +5019,7 @@
      * Resolves runner metadata for prompt status lines.
      */
     function getRunnerMetadata(options, actualRunnerModel) {
-        var _a;
-        const runnerName = options.agentName ? (_a = RUNNER_LABELS[options.agentName]) !== null && _a !== void 0 ? _a : 'unknown' : 'unknown';
+        const runnerName = options.agentName ? getHarnessDefinition(options.agentName).label : 'unknown';
         if (options.agentName === 'openai-codex' ||
             options.agentName === 'github-copilot' ||
             options.agentName === 'gemini') {
@@ -4884,16 +5065,87 @@
         process.exit(1);
     }
 
+    /**
+     * Builds the `## Projects` prompt section explaining the agent-owned projects convention.
+     *
+     * The section is part of the prompt of every harness, so each coding agent knows it has its
+     * own isolated project folders it fully controls and how to reference them in the chat.
+     */
+    function buildAgentProjectsPromptSection(options = {}) {
+        const { projectsUrlPath } = options;
+        return _spaceTrim.spaceTrim((block) => `
+            ## Projects
+
+            You have your own projects folder \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` in the current working directory. Each direct subfolder of it is one project — your own isolated environment for persistent work.
+
+            - 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.
+
+            ${block(buildProjectReferenceInstructions(projectsUrlPath))}
+            ${block(buildProjectRuntimeInstructions(options.projectRuntimeApi))}
+        `);
+    }
+    /**
+     * Builds the part of the section explaining how to reference projects in chat answers.
+     */
+    function buildProjectReferenceInstructions(projectsUrlPath) {
+        if (!projectsUrlPath) {
+            return _spaceTrim.spaceTrim(`
+            When you mention a project or its files in your answer, reference them by the project name and the file path inside the project, for example \`${AGENT_PROJECTS_DIRECTORY_PATH}/my-website/index.html\`.
+        `);
+        }
+        return _spaceTrim.spaceTrim(`
+        You can link any project or any file of any project into the chat answer as a markdown link:
+
+        - Link one file: \`[index.html](${projectsUrlPath}/<project-name>/files/<file-path>)\` — for example \`[Homepage](${projectsUrlPath}/my-website/files/index.html)\`
+        - Link the projects dashboard listing all your projects: \`[My projects](${projectsUrlPath})\`
+
+        Use these links whenever you want to show the user a file you created or changed in a project.
+    `);
+    }
+    /**
+     * Builds instructions for running projects through the Agents Server runtime API.
+     */
+    function buildProjectRuntimeInstructions(projectRuntimeApi) {
+        if (!projectRuntimeApi) {
+            return '';
+        }
+        return _spaceTrim.spaceTrim(`
+        You can make a project runnable in the user's browser by asking the Agents Server to start it:
+
+        - The server automatically runs \`npm run dev\` for a project whose \`package.json\` declares a non-empty \`dev\` script.
+        - Otherwise, the server starts a static file server for the project.
+        - If you need to run your own long-lived dev process, ask only for \`assign_port\`, then start your process on the returned \`runtime.port\`.
+        - Always include the returned \`runtime.url\` in your answer when the user should open the running project.
+
+        Examples:
+
+        \`\`\`bash
+        curl -sS -X POST "$${projectRuntimeApi.serverUrlEnvironmentVariableName}/api/internal/agent-project-runtimes" \\
+          -H "Content-Type: application/json" \\
+          -H "x-user-chat-worker-token: $${projectRuntimeApi.tokenEnvironmentVariableName}" \\
+          -d '{"action":"start","agentPermanentId":"${projectRuntimeApi.agentPermanentId}","projectName":"<project-name>"}'
+
+        curl -sS -X POST "$${projectRuntimeApi.serverUrlEnvironmentVariableName}/api/internal/agent-project-runtimes" \\
+          -H "Content-Type: application/json" \\
+          -H "x-user-chat-worker-token: $${projectRuntimeApi.tokenEnvironmentVariableName}" \\
+          -d '{"action":"assign_port","agentPermanentId":"${projectRuntimeApi.agentPermanentId}","projectName":"<project-name>"}'
+        \`\`\`
+    `);
+    }
+
     /**
      * Builds the prompt sent to the selected coding runner for one queued user-thread book.
      */
-    function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage) {
+    function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage, options = {}) {
         return _spaceTrim.spaceTrim((block) => `
                 # Answer 1 user question
 
                 -   Read \`${messageRelativePath}\` and answer the most recent \`MESSAGE @User\`
                 -   Only change the queued message file by appending one new \`MESSAGE @Agent\` block
-                -   Do not modify any other file in the repository
+                -   Do not modify any other file in the repository, except files inside your own \`${AGENT_PROJECTS_DIRECTORY_PATH}/\` directory
 
                 ## Rules for the answering
 
@@ -4929,34 +5181,46 @@
 
                 - 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(buildAgentProjectsPromptSection(options))}
+
                 ## This is how you should behave
 
                 ${block(agentSystemMessage)}
             `);
     }
 
-    /**
-     * Builds a normalized temporary shell script path for prompt runners.
-     */
-    function buildTemporaryPromptScriptPath(options) {
-        const sourceFileName = path.basename(options.sourceFileName);
-        const scriptFileName = `${sourceFileName.replace(/\.[^.]+$/u, '')}${options.suffix || ''}.sh`;
-        return resolvePromptbookTemporaryPath(options.projectPath, options.scriptDirectoryName, scriptFileName);
-    }
-
     /**
      * Temporary subdirectory used for agent-message runner shell scripts.
+     *
+     * @private internal constant of agent-message runtime paths
      */
     const AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME = 'agent-messages';
+    /**
+     * File extension used for temporary prompt-runner shell scripts.
+     *
+     * @private internal constant of agent-message runtime paths
+     */
+    const AGENT_MESSAGE_SCRIPT_EXTENSION = '.sh';
+    /**
+     * Builds the temporary shell script path used by one queued agent-message harness run.
+     *
+     * @param projectPath - Local agent project path containing the message queue.
+     * @param sourceFileName - Queued message filename used to name the temporary shell script.
+     * @returns Temporary shell script path.
+     * @private internal utility of agent-message runners
+     */
+    function buildAgentMessageScriptPathFromFileName(projectPath, sourceFileName) {
+        const sourceFileBasename = path.basename(sourceFileName);
+        const scriptFileName = `${sourceFileBasename.replace(/\.[^.]+$/u, '')}${AGENT_MESSAGE_SCRIPT_EXTENSION}`;
+        return resolvePromptbookTemporaryPath(projectPath, AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME, scriptFileName);
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * Builds a temporary script path for one agent message runner invocation.
      */
     function buildAgentMessageScriptPath(projectPath, messageFile) {
-        return buildTemporaryPromptScriptPath({
-            projectPath,
-            scriptDirectoryName: AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME,
-            sourceFileName: messageFile.fileName,
-        });
+        return buildAgentMessageScriptPathFromFileName(projectPath, messageFile.fileName);
     }
 
     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"}];
@@ -14507,6 +14771,7 @@
      * - META TITLE: Sets the agent's display title
      * - META DESCRIPTION: Sets the agent's description
      * - META INPUT PLACEHOLDER: Sets chat input placeholder text
+     * - META THINKING MESSAGE: Adds custom thinking placeholder variants
      * - META [ANYTHING]: Any other meta information in uppercase format
      *
      * These commitments are special because they don't affect the system message,
@@ -14522,6 +14787,7 @@
      * META TITLE Professional Assistant
      * META DESCRIPTION An AI assistant specialized in business tasks
      * META INPUT PLACEHOLDER Write a message...
+     * META THINKING MESSAGE Thinking...
      * META AUTHOR John Doe
      * META VERSION 1.0
      * ```
@@ -14562,6 +14828,7 @@
             - **META TITLE** - Sets the agent's display title
             - **META DESCRIPTION** - Sets the agent's description
             - **META INPUT PLACEHOLDER** - Sets chat input placeholder text
+            - **META THINKING MESSAGE** - Adds custom thinking placeholder variants
             - **META [ANYTHING]** - Any other meta information in uppercase format
 
             ## Key aspects
@@ -14570,6 +14837,7 @@
             - Used for visual representation and attribution in user interfaces
             - Multiple META commitments of different types can be used
             - Multiple META LINK commitments can be used for different social profiles
+            - Multiple META THINKING MESSAGE commitments can be used for different thinking placeholder variants
             - If multiple META commitments of the same type are specified, the last one takes precedence (except for LINK)
 
             ## Examples
@@ -21368,6 +21636,68 @@
     }
     // Note: [💞] Ignore a discrepancy between file name and entity name
 
+    /**
+     * META THINKING MESSAGE commitment definition.
+     *
+     * The `META THINKING MESSAGE` commitment adds one custom thinking placeholder
+     * variant used by chat UIs while an agent is composing a reply.
+     *
+     * @private Metadata-only commitment used by Agents Server chat UIs.
+     */
+    class MetaThinkingMessageCommitmentDefinition extends BaseCommitmentDefinition {
+        constructor() {
+            super('META THINKING MESSAGE');
+        }
+        /**
+         * Short one-line description of META THINKING MESSAGE.
+         */
+        get description() {
+            return 'Add a custom thinking placeholder shown while the agent replies.';
+        }
+        /**
+         * Icon for this commitment.
+         */
+        get icon() {
+            return '💭';
+        }
+        /**
+         * Markdown documentation for META THINKING MESSAGE commitment.
+         */
+        get documentation() {
+            return _spaceTrim.spaceTrim(`
+            # META THINKING MESSAGE
+
+            Adds one custom placeholder variant shown while the agent is composing a reply.
+
+            ## Key aspects
+
+            - Does not modify model behavior, system message, or tools.
+            - Multiple \`META THINKING MESSAGE\` commitments define multiple variants.
+            - Chat UIs randomly rotate between the configured variants while the reply is running.
+            - When no non-empty variants are configured, the server-level \`THINKING_MESSAGES\` metadata is used.
+            - Supports multiline markdown content.
+
+            ## Example
+
+            \`\`\`book
+            Helpful Assistant
+
+            META THINKING MESSAGE Thinking...
+            META THINKING MESSAGE Processing...
+            META THINKING MESSAGE
+
+            Doing
+            extra **hard** work
+            \`\`\`
+        `);
+        }
+        applyToAgentModelRequirements(requirements, content) {
+            // META THINKING MESSAGE is metadata only and does not alter model requirements.
+            return requirements;
+        }
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * META VISIBILITY commitment definition.
      *
@@ -23446,6 +23776,7 @@
               1. **One-shot URL fetching**: Simple function to fetch and scrape URL content (active)
               2. **Running browser**: For complex tasks like scrolling, clicking, form filling, etc. (runtime-dependent)
             - The actual browser tool usage is handled by the agent runtime
+            - On the Agents Server, every agent browses in its own persistent isolated browser profile, so cookies and logged-in sessions survive across chats (the profile is linked from the agent wallet)
             - Allows the agent to fetch current information from websites and documents
             - Useful for research tasks, fact-checking, and accessing dynamic content
             - Supports various content types including HTML pages and PDF documents
@@ -29990,6 +30321,7 @@
         new MetaDomainCommitmentDefinition(),
         new MetaDisclaimerCommitmentDefinition(),
         new MetaInputPlaceholderCommitmentDefinition(),
+        new MetaThinkingMessageCommitmentDefinition(),
         new MetaVisibilityCommitmentDefinition(),
         new MetaCommitmentDefinition(),
         new MetaVoiceCommitmentDefinition(),
@@ -31341,6 +31673,7 @@
         'META DESCRIPTION': applyMetaDescriptionContent,
         'META DISCLAIMER': applyMetaDisclaimerContent,
         'META INPUT PLACEHOLDER': applyMetaInputPlaceholderContent,
+        'META THINKING MESSAGE': applyMetaThinkingMessageContent,
         'MESSAGE SUFFIX': applyMessageSuffixContent,
         'META COLOR': applyMetaColorContent,
         'META FONT': applyMetaFontContent,
@@ -31431,6 +31764,16 @@
     function applyMetaInputPlaceholderContent(state, content) {
         state.meta.inputPlaceholder = _spaceTrim.spaceTrim(content);
     }
+    /**
+     * Applies one META THINKING MESSAGE content block into the custom thinking-message variants.
+     */
+    function applyMetaThinkingMessageContent(state, content) {
+        const thinkingMessage = _spaceTrim.spaceTrim(content);
+        if (!thinkingMessage) {
+            return;
+        }
+        state.thinkingMessages = [...(state.thinkingMessages || []), thinkingMessage];
+    }
     /**
      * Applies MESSAGE SUFFIX content into the canonical `meta.messageSuffix` field.
      */
@@ -31799,6 +32142,7 @@
             capabilities: [],
             samples: [],
             knowledgeSources: [],
+            thinkingMessages: [],
             pendingUserMessage: null,
             knownKnowledgeSourceUrls: new Set(),
         };
@@ -31811,6 +32155,7 @@
             capabilities: state.capabilities,
             samples: state.samples,
             knowledgeSources: state.knowledgeSources,
+            thinkingMessages: state.thinkingMessages,
         };
     }
     /**
@@ -31850,6 +32195,7 @@
             permanentId: parsedProfile.meta.id,
             personaDescription,
             initialMessage,
+            thinkingMessages: parsedProfile.thinkingMessages,
             meta: parsedProfile.meta,
             links: parsedProfile.links,
             parameters: parseParameters(agentSource),
@@ -43286,7 +43632,7 @@
      *
      * @private within the repository
      */
-    function locateApp(options) {
+    async function locateApp(options) {
         if (!$isRunningInNode()) {
             throw new EnvironmentMismatchError('Locating apps works only in Node.js environment');
         }