@promptbook/node 0.113.0-8 → 0.114.0-0

package/esm/index.es.js

@@ -1,8 +1,8 @@
 import { join, dirname, basename, isAbsolute, resolve, relative } from 'path';
 import { unlink, mkdir, appendFile, writeFile, readFile, stat, access, constants, readdir, watch, rm } from 'fs/promises';
+import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import colors from 'colors';
 import { spawn } from 'child_process';
-import _spaceTrim, { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { fileSearchTool, tool, Agent as Agent$1, webSearchTool, run, setDefaultOpenAIClient, setDefaultOpenAIKey } from '@openai/agents';
 import { fileURLToPath } from 'url';
 import { Readability } from '@mozilla/readability';
@@ -36,7 +36,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.113.0-8';
+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
@@ -73,6 +73,15 @@ const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PAT
  * @public exported from `@promptbook/node`
  */
 const AGENT_FAILED_MESSAGES_DIRECTORY_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
@@ -381,6 +390,34 @@ function $randomToken(randomness) {
 // TODO: [🤶] Maybe export through `@promptbook/utils` or `@promptbook/random` package
 // TODO: Maybe use nanoid instead https://github.com/ai/nanoid
 
+/**
+ * Increase the level of all headings in the markdown content
+ *
+ * @example h1 -> h2, h2 -> h3, ...
+ * @param content The markdown content
+ * @returns The markdown with increased headings
+ */
+function increaseHeadings(content) {
+    const lines = content.split(/\r?\n/);
+    let inCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.startsWith('```')) {
+            inCodeBlock = !inCodeBlock;
+        }
+        if (inCodeBlock) {
+            continue;
+        }
+        const headingMatch = line.match(/^(#+)(.*)/);
+        if (headingMatch) {
+            const headingLevel = headingMatch[1].length;
+            const headingText = headingMatch[2];
+            lines[i] = `${'#'.repeat(headingLevel + 1)}${headingText}`;
+        }
+    }
+    return lines.join('\n');
+}
+
 /**
  * Appends optional coding context to a runner prompt.
  */
@@ -393,7 +430,13 @@ function appendCoderContext(prompt, context) {
     if (normalizedPrompt === '') {
         return normalizedContext;
     }
-    return `${normalizedPrompt}\n\n${normalizedContext}`;
+    return spaceTrim$1((block) => `
+            ${block(normalizedPrompt)}
+
+            ## Context
+        
+            ${block(increaseHeadings(normalizedContext))}
+        `);
 }
 
 /**
@@ -435,48 +478,6 @@ async function withPromptRuntimeLog(scriptPath, handler, options) {
     }
 }
 
-/**
- * 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.
  *
@@ -522,6 +523,127 @@ function take(initialValue) {
     });
 }
 
+/**
+ * Validates that a channel value is a valid number within the range of 0 to 255.
+ * Throws an error if the value is not valid.
+ *
+ * @param channelName - The name of the channel being validated.
+ * @param value - The value of the channel to validate.
+ * @throws Will throw an error if the value is not a valid channel number.
+ *
+ * @private util of `@promptbook/color`
+ */
+function checkChannelValue(channelName, value) {
+    if (typeof value !== 'number') {
+        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
+    }
+    if (isNaN(value)) {
+        throw new Error(`${channelName} channel value is NaN`);
+    }
+    if (Math.round(value) !== value) {
+        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
+    }
+    if (value < 0) {
+        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
+    }
+    if (value > 255) {
+        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
+    }
+}
+
+/**
+ * Shared immutable channel storage and serialization helpers for `Color`.
+ *
+ * @private base class of Color
+ */
+class ColorValue {
+    constructor(red, green, blue, alpha = 255) {
+        this.red = red;
+        this.green = green;
+        this.blue = blue;
+        this.alpha = alpha;
+        checkChannelValue('Red', red);
+        checkChannelValue('Green', green);
+        checkChannelValue('Blue', blue);
+        checkChannelValue('Alpha', alpha);
+    }
+    /**
+     * Shortcut for `red` property
+     * Number from 0 to 255
+     * @alias red
+     */
+    get r() {
+        return this.red;
+    }
+    /**
+     * Shortcut for `green` property
+     * Number from 0 to 255
+     * @alias green
+     */
+    get g() {
+        return this.green;
+    }
+    /**
+     * Shortcut for `blue` property
+     * Number from 0 to 255
+     * @alias blue
+     */
+    get b() {
+        return this.blue;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get a() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for `alpha` property
+     * Number from 0 (transparent) to 255 (opaque)
+     * @alias alpha
+     */
+    get opacity() {
+        return this.alpha;
+    }
+    /**
+     * Shortcut for 1-`alpha` property
+     */
+    get transparency() {
+        return 255 - this.alpha;
+    }
+    clone() {
+        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
+    }
+    toString() {
+        return this.toHex();
+    }
+    toHex() {
+        if (this.alpha === 255) {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}`;
+        }
+        else {
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
+                .toString(16)
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
+        }
+    }
+    toRgb() {
+        if (this.alpha === 255) {
+            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+        }
+        else {
+            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
+        }
+    }
+    toHsl() {
+        throw new Error(`Getting HSL is not implemented`);
+    }
+}
+
 /**
  * 🎨 List of all 140 color names which are supported by CSS
  *
@@ -681,127 +803,6 @@ const CSS_COLORS = {
 };
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
-/**
- * Validates that a channel value is a valid number within the range of 0 to 255.
- * Throws an error if the value is not valid.
- *
- * @param channelName - The name of the channel being validated.
- * @param value - The value of the channel to validate.
- * @throws Will throw an error if the value is not a valid channel number.
- *
- * @private util of `@promptbook/color`
- */
-function checkChannelValue(channelName, value) {
-    if (typeof value !== 'number') {
-        throw new Error(`${channelName} channel value is not number but ${typeof value}`);
-    }
-    if (isNaN(value)) {
-        throw new Error(`${channelName} channel value is NaN`);
-    }
-    if (Math.round(value) !== value) {
-        throw new Error(`${channelName} channel is not whole number, it is ${value}`);
-    }
-    if (value < 0) {
-        throw new Error(`${channelName} channel is lower than 0, it is ${value}`);
-    }
-    if (value > 255) {
-        throw new Error(`${channelName} channel is greater than 255, it is ${value}`);
-    }
-}
-
-/**
- * Shared immutable channel storage and serialization helpers for `Color`.
- *
- * @private base class of Color
- */
-class ColorValue {
-    constructor(red, green, blue, alpha = 255) {
-        this.red = red;
-        this.green = green;
-        this.blue = blue;
-        this.alpha = alpha;
-        checkChannelValue('Red', red);
-        checkChannelValue('Green', green);
-        checkChannelValue('Blue', blue);
-        checkChannelValue('Alpha', alpha);
-    }
-    /**
-     * Shortcut for `red` property
-     * Number from 0 to 255
-     * @alias red
-     */
-    get r() {
-        return this.red;
-    }
-    /**
-     * Shortcut for `green` property
-     * Number from 0 to 255
-     * @alias green
-     */
-    get g() {
-        return this.green;
-    }
-    /**
-     * Shortcut for `blue` property
-     * Number from 0 to 255
-     * @alias blue
-     */
-    get b() {
-        return this.blue;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get a() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for `alpha` property
-     * Number from 0 (transparent) to 255 (opaque)
-     * @alias alpha
-     */
-    get opacity() {
-        return this.alpha;
-    }
-    /**
-     * Shortcut for 1-`alpha` property
-     */
-    get transparency() {
-        return 255 - this.alpha;
-    }
-    clone() {
-        return take(this.createColor(this.red, this.green, this.blue, this.alpha));
-    }
-    toString() {
-        return this.toHex();
-    }
-    toHex() {
-        if (this.alpha === 255) {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}`;
-        }
-        else {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
-                .toString(16)
-                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
-        }
-    }
-    toRgb() {
-        if (this.alpha === 255) {
-            return `rgb(${this.red}, ${this.green}, ${this.blue})`;
-        }
-        else {
-            return `rgba(${this.red}, ${this.green}, ${this.blue}, ${Math.round((this.alpha / 255) * 100)}%)`;
-        }
-    }
-    toHsl() {
-        throw new Error(`Getting HSL is not implemented`);
-    }
-}
-
 /**
  * Checks if the given value is a valid hex color string
  *
@@ -1781,6 +1782,110 @@ class UnexpectedError extends Error {
     }
 }
 
+/**
+ * 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$1(`
+                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`
  *
@@ -2775,6 +2880,31 @@ const OPENAI_MODELS = exportJson({
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * Pattern that matches durations like "1h", "30m", "5s", "1h30m", "1h30m5s".
+ */
+/**
+ * Formats a duration in milliseconds into a compact human-readable string.
+ *
+ * Examples: `3600000` → `"1h"`, `90000` → `"1m 30s"`, `5000` → `"5s"`.
+ *
+ * @private internal utility of `ptbk coder run`
+ */
+function formatDurationMs(ms) {
+    const totalSeconds = Math.ceil(ms / 1000);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+
 /**
  * Formats one unknown error-like value into readable text for logs and feedback.
  */
@@ -3002,6 +3132,55 @@ async function $runGoScriptWithOutput(options) {
     });
 }
 
+/**
+ * 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.
  */
@@ -3012,14 +3191,209 @@ const CLAUDE_PROMPT_DELIMITER = 'CLAUDE_PROMPT';
 function buildClaudeScript(options) {
     const MODEL_ARGUMENT = options.model ? ` --model ${options.model}` : '';
     const THINKING_LEVEL_ARGUMENT = options.thinkingLevel ? ` --effort ${options.thinkingLevel}` : '';
+    const RESUME_SESSION_ARGUMENT = options.resumeSessionId
+        ? ` --resume ${quoteShellArgument(options.resumeSessionId)}`
+        : '';
     return spaceTrim((block) => `
-            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
+            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT}${RESUME_SESSION_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
 
             ${block(options.prompt)}
 
             ${CLAUDE_PROMPT_DELIMITER}
         `);
 }
+/**
+ * Quotes one shell argument for the generated Bash script.
+ */
+function quoteShellArgument(value) {
+    return JSON.stringify(value);
+}
+
+/**
+ * Parses all JSON lines from Claude Code output while ignoring shell prefixes and stack traces.
+ */
+function parseClaudeCodeOutputEvents(output) {
+    return output
+        .split(/\r?\n/u)
+        .map(parseClaudeCodeOutputLine)
+        .filter((event) => event !== undefined);
+}
+/**
+ * Finds the final Claude Code result event in a stream-json output blob.
+ */
+function findClaudeCodeResultEvent(output) {
+    return parseClaudeCodeOutputEvents(output).find((event) => event.type === 'result');
+}
+/**
+ * Parses one output line when it contains a JSON object.
+ */
+function parseClaudeCodeOutputLine(line) {
+    const jsonStartIndex = line.indexOf('{');
+    if (jsonStartIndex === -1) {
+        return undefined;
+    }
+    const possibleJson = line.slice(jsonStartIndex).trim();
+    try {
+        const parsed = JSON.parse(possibleJson);
+        if (isClaudeCodeOutputEvent(parsed)) {
+            return parsed;
+        }
+    }
+    catch (_a) {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Checks whether an unknown parsed JSON value has the object shape expected from Claude Code events.
+ */
+function isClaudeCodeOutputEvent(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Number of milliseconds added after Claude's reported reset timestamp before retrying.
+ */
+const CLAUDE_CODE_SESSION_LIMIT_RESET_BUFFER_MS = 30 * 1000;
+/**
+ * Fallback delay used when Claude reports a session limit without a machine-readable reset timestamp.
+ */
+const DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS = 10 * 60 * 1000;
+/**
+ * Extracts a Claude Code session-limit failure from a thrown runner error.
+ */
+function extractClaudeCodeSessionLimitFromError(error) {
+    return extractClaudeCodeSessionLimitFromOutput(formatUnknownErrorDetails(error));
+}
+/**
+ * Extracts a Claude Code session-limit failure from raw stream-json output.
+ */
+function extractClaudeCodeSessionLimitFromOutput(output) {
+    var _a, _b, _c, _d, _e;
+    const events = parseClaudeCodeOutputEvents(output);
+    const rejectedRateLimitEvent = events.find(isRejectedRateLimitEvent);
+    const sessionLimitResultEvent = events.find(isSessionLimitResultEvent);
+    const sessionLimitTextEvent = events.find(isSessionLimitTextEvent);
+    if (!sessionLimitResultEvent && !sessionLimitTextEvent) {
+        return undefined;
+    }
+    const sessionId = findClaudeCodeSessionId(events);
+    if (!sessionId) {
+        return undefined;
+    }
+    const resetDate = extractResetDate(rejectedRateLimitEvent);
+    const rateLimitType = (_b = (_a = rejectedRateLimitEvent === null || rejectedRateLimitEvent === void 0 ? void 0 : rejectedRateLimitEvent.rate_limit_info) === null || _a === void 0 ? void 0 : _a.rateLimitType) !== null && _b !== void 0 ? _b : (_c = sessionLimitResultEvent === null || sessionLimitResultEvent === void 0 ? void 0 : sessionLimitResultEvent.rate_limit_info) === null || _c === void 0 ? void 0 : _c.rateLimitType;
+    const summary = (_e = (_d = extractSessionLimitSummary(sessionLimitResultEvent)) !== null && _d !== void 0 ? _d : extractSessionLimitSummary(sessionLimitTextEvent)) !== null && _e !== void 0 ? _e : 'Claude Code reported a session limit.';
+    return {
+        sessionId,
+        resetDate,
+        rateLimitType,
+        summary,
+    };
+}
+/**
+ * Computes how long to wait before trying to resume the Claude Code session.
+ */
+function getClaudeCodeSessionLimitDelayMs(sessionLimit, nowMs = Date.now()) {
+    if (!sessionLimit.resetDate) {
+        return DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS;
+    }
+    return Math.max(0, sessionLimit.resetDate.getTime() - nowMs + CLAUDE_CODE_SESSION_LIMIT_RESET_BUFFER_MS);
+}
+/**
+ * Builds the follow-up prompt sent into a resumed Claude Code session after its limit resets.
+ */
+function buildClaudeCodeSessionResurrectionPrompt(originalPrompt, sessionId) {
+    return spaceTrim((block) => `
+            ## Claude Code session resurrection
+
+            You are resuming Claude Code session \`${sessionId}\` after Claude reported a session limit.
+            Continue the same task from the existing repository and session state.
+            Do not discard useful context, completed analysis, or file changes from the resumed session.
+
+            The original prompt is repeated below as reference in case the resumed session needs it.
+
+            ## Original prompt
+
+            ${block(originalPrompt)}
+        `);
+}
+/**
+ * Builds a compact one-line label for logs and terminal UI messages.
+ */
+function formatClaudeCodeSessionLimitForDisplay(sessionLimit) {
+    const resetSuffix = sessionLimit.resetDate
+        ? `, resets at ${sessionLimit.resetDate.toISOString()}`
+        : `, retrying every ${formatDurationMs(DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS)}`;
+    const rateLimitSuffix = sessionLimit.rateLimitType ? ` (${sessionLimit.rateLimitType})` : '';
+    return `${sessionLimit.summary}${rateLimitSuffix}${resetSuffix}`;
+}
+/**
+ * Returns true when the event is an explicit rejected Claude Code rate-limit event.
+ */
+function isRejectedRateLimitEvent(event) {
+    var _a;
+    return event.type === 'rate_limit_event' && ((_a = event.rate_limit_info) === null || _a === void 0 ? void 0 : _a.status) === 'rejected';
+}
+/**
+ * Returns true when the final result reports the Claude session limit.
+ */
+function isSessionLimitResultEvent(event) {
+    return (event.type === 'result' &&
+        event.is_error === true &&
+        event.api_error_status === 429 &&
+        isSessionLimitText(event.result));
+}
+/**
+ * Returns true when any assistant event reports the Claude session limit in text.
+ */
+function isSessionLimitTextEvent(event) {
+    if (event.error !== 'rate_limit') {
+        return false;
+    }
+    return isSessionLimitText(extractSessionLimitSummary(event));
+}
+/**
+ * Extracts the first session id reported by Claude Code.
+ */
+function findClaudeCodeSessionId(events) {
+    return events.map((event) => event.session_id).find((sessionId) => Boolean(sessionId));
+}
+/**
+ * Extracts Claude's reset timestamp from a rejected rate-limit event.
+ */
+function extractResetDate(event) {
+    var _a;
+    const resetsAt = (_a = event === null || event === void 0 ? void 0 : event.rate_limit_info) === null || _a === void 0 ? void 0 : _a.resetsAt;
+    if (typeof resetsAt !== 'number' || !Number.isFinite(resetsAt)) {
+        return undefined;
+    }
+    const resetDate = new Date(resetsAt * 1000);
+    if (Number.isNaN(resetDate.getTime())) {
+        return undefined;
+    }
+    return resetDate;
+}
+/**
+ * Extracts a human-readable session-limit summary from an event.
+ */
+function extractSessionLimitSummary(event) {
+    var _a, _b;
+    if (!event) {
+        return undefined;
+    }
+    if (typeof event.result === 'string' && event.result.trim()) {
+        return event.result.trim();
+    }
+    const textContent = (_b = (_a = event.message) === null || _a === void 0 ? void 0 : _a.content) === null || _b === void 0 ? void 0 : _b.map((content) => { var _a; return (content.type === 'text' ? (_a = content.text) === null || _a === void 0 ? void 0 : _a.trim() : undefined); }).find((text) => Boolean(text));
+    return textContent;
+}
+/**
+ * Checks whether a text value names the Claude Code session limit.
+ */
+function isSessionLimitText(text) {
+    return /\bsession\s+limit\b/iu.test(text !== null && text !== void 0 ? text : '');
+}
 
 /**
  * Represents the uncertain value
@@ -3095,14 +3469,8 @@ const UNCERTAIN_USAGE = $deepFreeze({
 function parseClaudeCodeJsonOutput(output) {
     var _a, _b, _c, _d;
     try {
-        // Extract JSON from the output - it should be a line starting with {"type":"result"
-        const lines = output.split(/\r?\n/);
-        const jsonLine = lines.find((line) => line.trim().startsWith('{"type":"result"'));
-        if (!jsonLine) {
-            return UNCERTAIN_USAGE;
-        }
-        const parsed = JSON.parse(jsonLine);
-        if (parsed.type !== 'result') {
+        const parsed = findClaudeCodeResultEvent(output);
+        if (!parsed) {
             return UNCERTAIN_USAGE;
         }
         const totalInputTokens = (((_a = parsed.usage) === null || _a === void 0 ? void 0 : _a.input_tokens) || 0) +
@@ -3146,6 +3514,10 @@ function parseClaudeCodeJsonOutput(output) {
     }
 }
 
+/**
+ * Polling interval used while waiting for Claude Code session limits to reset.
+ */
+const CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS = 30 * 1000;
 /**
  * Runs prompts via the Claude Code CLI.
  */
@@ -3161,22 +3533,98 @@ class ClaudeCodeRunner {
      * Runs the prompt using Claude Code and parses usage output.
      */
     async runPrompt(options) {
+        let resumeSessionId;
+        let prompt = options.prompt;
+        let resurrectionCount = 0;
+        while (true) {
+            const output = await this.runClaudeCodeOnce({
+                ...options,
+                prompt,
+                resumeSessionId,
+            }).catch(async (error) => {
+                const sessionLimit = extractClaudeCodeSessionLimitFromError(error);
+                if (!sessionLimit) {
+                    throw error;
+                }
+                resurrectionCount++;
+                await waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options);
+                resumeSessionId = sessionLimit.sessionId;
+                prompt = buildClaudeCodeSessionResurrectionPrompt(options.prompt, sessionLimit.sessionId);
+                return undefined;
+            });
+            if (output === undefined) {
+                continue;
+            }
+            const sessionLimit = extractClaudeCodeSessionLimitFromOutput(output);
+            if (sessionLimit) {
+                resurrectionCount++;
+                await waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options);
+                resumeSessionId = sessionLimit.sessionId;
+                prompt = buildClaudeCodeSessionResurrectionPrompt(options.prompt, sessionLimit.sessionId);
+                continue;
+            }
+            const usage = parseClaudeCodeJsonOutput(output);
+            return { usage };
+        }
+    }
+    /**
+     * Runs one Claude Code CLI process and returns its raw output.
+     */
+    async runClaudeCodeOnce(options) {
         const scriptContent = buildClaudeScript({
             prompt: options.prompt,
             model: this.options.model,
             thinkingLevel: this.options.thinkingLevel,
+            resumeSessionId: options.resumeSessionId,
         });
-        const output = await $runGoScriptWithOutput({
+        return await $runGoScriptWithOutput({
             scriptPath: options.scriptPath,
             scriptContent,
             logPath: options.logPath,
             shouldPrintLiveOutput: options.shouldPrintLiveOutput,
             preserveArtifactsOnSuccess: options.preserveArtifactsOnSuccess,
         });
-        const usage = parseClaudeCodeJsonOutput(output);
-        return { usage };
     }
 }
+/**
+ * Waits until the Claude Code session can be resumed, keeping terminal status clear.
+ */
+async function waitForClaudeCodeSessionLimitReset(sessionLimit, resurrectionCount, options) {
+    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.yellow(`[claude-code] Session limit detected for ${sessionLimit.sessionId}. Resurrection #${resurrectionCount} will resume with --resume after ${formatDurationMs(delayMs)}. ${resetSummary}`));
+    }
+    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`,
+    }));
+}
+/**
+ * Formats a Claude Code session id for compact terminal status lines.
+ */
+function formatClaudeCodeSessionIdForDisplay(sessionId) {
+    if (sessionId.length <= 8) {
+        return sessionId;
+    }
+    return `${sessionId.slice(0, 8)}...`;
+}
 
 /**
  * Creates a temporary script file, runs it, and cleans it up unless preservation is requested or the run fails.
@@ -3775,6 +4223,27 @@ class ProgressiveBackoff {
     }
 }
 
+// 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.
  */
@@ -3791,10 +4260,28 @@ function buildCodexScript(options) {
     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
@@ -3813,11 +4300,15 @@ function buildCodexScript(options) {
         '',
         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}" \\`,
@@ -4019,6 +4510,37 @@ function resolveCodexPricing(modelName) {
     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.
  */
@@ -4128,12 +4650,6 @@ const RATE_LIMIT_BACKOFF_MAX_MS = 30 * 60 * 1000;
  * 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.
  */
@@ -4211,7 +4727,10 @@ class OpenAiCodexRunner {
                     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);
@@ -4223,13 +4742,18 @@ class OpenAiCodexRunner {
                     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.yellow(`[codex] Rate limit/quota detected (${summary}). Retry #${retryIndex} in ${formatDelay(delayMs)} at ${retryAt}.`));
                 }
-                await waitForRetryDelay(delayMs, options);
+                await waitForRetryDelay({
+                    delayMs,
+                    retryDeadlineTimeMs,
+                    promptRunOptions: options,
+                });
             }
         }
     }
@@ -4237,20 +4761,21 @@ class OpenAiCodexRunner {
 /**
  * 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`,
+            }));
+        },
+    });
 }
 
 /**
@@ -4388,17 +4913,6 @@ const DEFAULT_CODEX_MODEL = 'gpt-5.2-codex';
  * 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.
  *
@@ -4490,8 +5004,7 @@ function createRunnerResolution(options, runner, actualRunnerModel) {
  * 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') {
@@ -4537,16 +5050,87 @@ function exitForMissingModel(agentName, availableModels, exampleUsages) {
     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$1((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$1(`
+            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$1(`
+        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$1(`
+        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$1((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
 
@@ -4582,34 +5166,46 @@ function buildAgentMessagePrompt(messageRelativePath, agentSystemMessage) {
 
                 - 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 = 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 = 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"}];
@@ -5072,6 +5668,95 @@ function pipelineJsonToString(pipelineJson) {
 // TODO: [🏛] Escape all
 // TODO: [🧠] Should be in generated .book.md file GENERATOR_WARNING
 
+/**
+ * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ *
+ * @public exported from `@promptbook/core`
+ */
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+    }
+}
+
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+function createPipelineValidationContext(pipeline) {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification$1(pipeline),
+    };
+}
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification$1(pipeline) {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts = [];
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+    return pipelineIdentificationParts.join('\n');
+}
+
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification, }) {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
+    }
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(spaceTrim$1((block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `));
+}
+
 /**
  * Order of keys in the pipeline JSON
  *
@@ -5184,17 +5869,138 @@ const LIMITS = {
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error indicates that the promptbook object has valid syntax (=can be parsed) but contains logical errors (like circular dependencies)
+ * Validates that task dependencies can be resolved without cycles or missing definitions.
  *
- * @public exported from `@promptbook/core`
+ * @private function of `validatePipeline`
  */
-class PipelineLogicError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PipelineLogicError';
-        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+function validatePipelineDependencyResolution({ pipeline, pipelineIdentification, }) {
+    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
+    let loopLimit = LOOP_LIMIT;
+    while (hasUnresolvedTasks(dependencyResolutionState)) {
+        if (loopLimit-- < 0) {
+            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
+        }
+        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
     }
 }
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitialDependencyResolutionState(pipeline) {
+    return {
+        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
+        unresolvedTasks: [...pipeline.tasks],
+    };
+}
+/**
+ * Checks whether dependency resolution still has tasks left to process.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function hasUnresolvedTasks({ unresolvedTasks }) {
+    return unresolvedTasks.length > 0;
+}
+/**
+ * Resolves the next batch of currently satisfiable tasks.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
+    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
+    if (currentlyResolvedTasks.length === 0) {
+        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
+    }
+    return {
+        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
+        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
+    };
+}
+/**
+ * Collects the parameter names that are already resolvable before dependency traversal starts.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createInitiallyResolvedParameterNames(pipeline) {
+    let resolvedParameterNames = pipeline.parameters
+        .filter(({ isInput }) => isInput)
+        .map(({ name }) => name);
+    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
+        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
+    }
+    return resolvedParameterNames;
+}
+/**
+ * Adds newly resolved task outputs to the resolved parameter list.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
+    return [
+        ...resolvedParameterNames,
+        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
+    ];
+}
+/**
+ * Selects tasks whose dependencies are already resolved.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
+    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
+}
+/**
+ * Creates the unexpected loop-limit error for dependency resolution.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createDependencyResolutionLoopLimitError(pipelineIdentification) {
+    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
+    return new UnexpectedError(spaceTrim$1((block) => `
+                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+
+                ${block(pipelineIdentification)}
+            `));
+}
+/**
+ * Creates the detailed error for unresolved or circular task dependencies.
+ *
+ * @private internal utility of `validatePipelineDependencyResolution`
+ */
+function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
+    return new PipelineLogicError(
+    // TODO: [🐎] DRY
+    spaceTrim$1((block) => `
+
+                Can not resolve some parameters:
+                Either you are using a parameter that is not defined, or there are some circular dependencies.
+
+                ${block(pipelineIdentification)}
+
+                **Can not resolve:**
+                ${block(unresolvedTasks
+        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
+        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
+        .join(' and ')}`)
+        .join('\n'))}
+
+                **Resolved:**
+                ${block(resolvedParameterNames
+        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+                **Reserved (which are available):**
+                ${block(resolvedParameterNames
+        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
+        .map((name) => `- Parameter \`{${name}}\``)
+        .join('\n'))}
+
+
+            `));
+}
 
 /**
  * Tests if given string is valid semantic version
@@ -5270,168 +6076,19 @@ function isValidPipelineUrl(url) {
 }
 // TODO: [🐠] Maybe more info why the URL is invalid
 
-/**
- * Validates PipelineJson if it is logically valid
- *
- * It checks:
- * -   if it has correct parameters dependency
- *
- * It does NOT check:
- * -   if it is valid json
- * -   if it is meaningful
- *
- * Note: [🔂] This function is idempotent.
- *
- * @param pipeline valid or invalid PipelineJson
- * @returns the same pipeline if it is logically valid
- * @throws {PipelineLogicError} on logical error in the pipeline
- *
- * @public exported from `@promptbook/core`
- */
-function validatePipeline(pipeline) {
-    if (IS_PIPELINE_LOGIC_VALIDATED) {
-        validatePipeline_InnerFunction(pipeline);
-    }
-    else {
-        try {
-            validatePipeline_InnerFunction(pipeline);
-        }
-        catch (error) {
-            if (!(error instanceof PipelineLogicError)) {
-                throw error;
-            }
-            console.error(spaceTrim$1((block) => `
-                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
-
-                        ${block(error.message)}
-                    `));
-        }
-    }
-    return pipeline;
-}
-/**
- * Validates pipeline inner function.
- *
- * @private internal function for `validatePipeline`
- */
-function validatePipeline_InnerFunction(pipeline) {
-    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
-    const context = createPipelineValidationContext(pipeline);
-    validatePipelineMetadata(context);
-    validatePipelineCollectionsStructure(context);
-    validatePipelineParameters(context);
-    validatePipelineTasks(context);
-    validatePipelineDependencyResolution(context);
-    // Note: Check that formfactor is corresponding to the pipeline interface
-    // TODO: !!6 Implement this
-    // pipeline.formfactorName
-}
-/**
- * Creates the shared validation context for one pipeline.
- *
- * @private internal utility of `validatePipeline`
- */
-function createPipelineValidationContext(pipeline) {
-    return {
-        pipeline,
-        pipelineIdentification: getPipelineIdentification$1(pipeline),
-    };
-}
-/**
- * Builds a short file/url identification block for validation errors.
- *
- * @private internal utility of `validatePipeline`
- */
-function getPipelineIdentification$1(pipeline) {
-    // Note: This is a 😐 implementation of [🚞]
-    const pipelineIdentificationParts = [];
-    if (pipeline.sourceFile !== undefined) {
-        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
-    }
-    if (pipeline.pipelineUrl !== undefined) {
-        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
-    }
-    return pipelineIdentificationParts.join('\n');
-}
 /**
  * Validates pipeline-level metadata fields.
  *
- * @private internal step of `validatePipeline`
+ * @private function of `validatePipeline`
  */
 function validatePipelineMetadata({ pipeline, pipelineIdentification }) {
     validatePipelineUrl(pipeline, pipelineIdentification);
     validatePipelineBookVersion(pipeline, pipelineIdentification);
 }
-/**
- * Validates that the expected top-level collections have array structure.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineCollectionsStructure({ pipeline, pipelineIdentification }) {
-    validatePipelineParametersCollection(pipeline, pipelineIdentification);
-    validatePipelineTasksCollection(pipeline, pipelineIdentification);
-}
-/**
- * Validates all pipeline parameter declarations.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameters({ pipeline, pipelineIdentification }) {
-    for (const parameter of pipeline.parameters) {
-        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
-    }
-}
-/**
- * Validates all pipeline tasks and their per-task invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTasks({ pipeline, pipelineIdentification }) {
-    // Note: All input parameters are defined - so that they can be used as result of some task
-    const definedParameters = createInitiallyDefinedParameters(pipeline);
-    for (const task of pipeline.tasks) {
-        validatePipelineTask(task, definedParameters, pipelineIdentification);
-    }
-}
-/**
- * Validates that task dependencies can be resolved without cycles or missing definitions.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineDependencyResolution({ pipeline, pipelineIdentification }) {
-    let dependencyResolutionState = createInitialDependencyResolutionState(pipeline);
-    let loopLimit = LOOP_LIMIT;
-    while (hasUnresolvedTasks(dependencyResolutionState)) {
-        if (loopLimit-- < 0) {
-            throw createDependencyResolutionLoopLimitError(pipelineIdentification);
-        }
-        dependencyResolutionState = resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification);
-    }
-}
-/**
- * Validates one pipeline parameter declaration.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
-    validateParameterDirection(parameter, pipelineIdentification);
-    validateParameterUsage(parameter, pipeline, pipelineIdentification);
-    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
-}
-/**
- * Validates one pipeline task and its invariants.
- *
- * @private internal step of `validatePipeline`
- */
-function validatePipelineTask(task, definedParameters, pipelineIdentification) {
-    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
-    validateTaskJokers(task, pipelineIdentification);
-    validateTaskExpectations(task, pipelineIdentification);
-}
 /**
  * Validates the pipeline URL, when present.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineMetadata`
  */
 function validatePipelineUrl(pipeline, pipelineIdentification) {
     if (pipeline.pipelineUrl === undefined || isValidPipelineUrl(pipeline.pipelineUrl)) {
@@ -5447,7 +6104,7 @@ function validatePipelineUrl(pipeline, pipelineIdentification) {
 /**
  * Validates the Promptbook version, when present.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineMetadata`
  */
 function validatePipelineBookVersion(pipeline, pipelineIdentification) {
     if (pipeline.bookVersion === undefined || isValidPromptbookVersion(pipeline.bookVersion)) {
@@ -5460,48 +6117,31 @@ function validatePipelineBookVersion(pipeline, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Validates that `pipeline.parameters` is an array.
+ * Validates all pipeline parameter declarations.
  *
- * @private internal utility of `validatePipeline`
+ * @private function of `validatePipeline`
  */
-function validatePipelineParametersCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.parameters)) {
-        return;
+function validatePipelineParameters({ pipeline, pipelineIdentification }) {
+    for (const parameter of pipeline.parameters) {
+        validatePipelineParameter(parameter, pipeline, pipelineIdentification);
     }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
-
-                ${block(pipelineIdentification)}
-            `));
 }
 /**
- * Validates that `pipeline.tasks` is an array.
+ * Validates one pipeline parameter declaration.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
-function validatePipelineTasksCollection(pipeline, pipelineIdentification) {
-    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
-    if (Array.isArray(pipeline.tasks)) {
-        return;
-    }
-    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
-    throw new ParseError(spaceTrim$1((block) => `
-                Pipeline is valid JSON but with wrong structure
-
-                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
-
-                ${block(pipelineIdentification)}
-            `));
+function validatePipelineParameter(parameter, pipeline, pipelineIdentification) {
+    validateParameterDirection(parameter, pipelineIdentification);
+    validateParameterUsage(parameter, pipeline, pipelineIdentification);
+    validateParameterDefinition(parameter, pipeline, pipelineIdentification);
 }
 /**
  * Validates that one parameter does not declare incompatible directions.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDirection(parameter, pipelineIdentification) {
     if (!parameter.isInput || !parameter.isOutput) {
@@ -5518,7 +6158,7 @@ function validateParameterDirection(parameter, pipelineIdentification) {
 /**
  * Validates that one intermediate parameter is actually consumed by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || parameter.isOutput || isParameterUsedByAnyTask(parameter, pipeline.tasks)) {
@@ -5537,7 +6177,7 @@ function validateParameterUsage(parameter, pipeline, pipelineIdentification) {
 /**
  * Validates that one non-input parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function validateParameterDefinition(parameter, pipeline, pipelineIdentification) {
     if (parameter.isInput || isParameterDefinedByAnyTask(parameter, pipeline.tasks)) {
@@ -5556,7 +6196,7 @@ function validateParameterDefinition(parameter, pipeline, pipelineIdentification
 /**
  * Checks whether one parameter is consumed by at least one task dependency list.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterUsedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.dependentParameterNames.includes(parameter.name));
@@ -5564,23 +6204,46 @@ function isParameterUsedByAnyTask(parameter, tasks) {
 /**
  * Checks whether one parameter is produced by at least one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineParameters`
  */
 function isParameterDefinedByAnyTask(parameter, tasks) {
     return tasks.some((task) => task.resultingParameterName === parameter.name);
 }
+
+/**
+ * Validates all pipeline tasks and their per-task invariants.
+ *
+ * @private function of `validatePipeline`
+ */
+function validatePipelineTasks({ pipeline, pipelineIdentification }) {
+    // Note: All input parameters are defined - so that they can be used as result of some task
+    const definedParameters = createInitiallyDefinedParameters(pipeline);
+    for (const task of pipeline.tasks) {
+        validatePipelineTask(task, definedParameters, pipelineIdentification);
+    }
+}
 /**
  * Collects the parameter names that are already defined before task validation starts.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function createInitiallyDefinedParameters(pipeline) {
     return new Set(pipeline.parameters.filter(({ isInput }) => isInput).map(({ name }) => name));
 }
+/**
+ * Validates one pipeline task and its invariants.
+ *
+ * @private internal utility of `validatePipelineTasks`
+ */
+function validatePipelineTask(task, definedParameters, pipelineIdentification) {
+    validateTaskResultingParameter(task, definedParameters, pipelineIdentification);
+    validateTaskJokers(task, pipelineIdentification);
+    validateTaskExpectations(task, pipelineIdentification);
+}
 /**
  * Validates one task result parameter declaration and marks it as defined.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskResultingParameter(task, definedParameters, pipelineIdentification) {
     if (definedParameters.has(task.resultingParameterName)) {
@@ -5602,7 +6265,7 @@ function validateTaskResultingParameter(task, definedParameters, pipelineIdentif
 /**
  * Validates joker parameters for one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokers(task, pipelineIdentification) {
     if (!hasTaskJokers(task)) {
@@ -5614,7 +6277,7 @@ function validateTaskJokers(task, pipelineIdentification) {
 /**
  * Checks whether one task declares any joker parameters.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function hasTaskJokers(task) {
     return !!task.jokerParameterNames && task.jokerParameterNames.length > 0;
@@ -5622,7 +6285,7 @@ function hasTaskJokers(task) {
 /**
  * Validates that a task has the required supporting features when using jokers.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskSupportsJokers(task, pipelineIdentification) {
     if (task.format || task.expectations /* <- TODO: Require at least 1 -> min <- expectation to use jokers */) {
@@ -5637,7 +6300,7 @@ function validateTaskSupportsJokers(task, pipelineIdentification) {
 /**
  * Validates that every joker parameter is also listed among task dependencies.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskJokerDependencies(task, pipelineIdentification) {
     for (const joker of task.jokerParameterNames) {
@@ -5654,7 +6317,7 @@ function validateTaskJokerDependencies(task, pipelineIdentification) {
 /**
  * Validates all expectation bounds configured on one task.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectations(task, pipelineIdentification) {
     if (!task.expectations) {
@@ -5669,7 +6332,7 @@ function validateTaskExpectations(task, pipelineIdentification) {
 /**
  * Validates the minimum and maximum expectation ordering for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
     if (min === undefined || max === undefined || min <= max) {
@@ -5684,7 +6347,7 @@ function validateTaskExpectationRange(unit, min, max, pipelineIdentification) {
 /**
  * Validates the minimum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMin(unit, min, pipelineIdentification) {
     if (min === undefined || min >= 0) {
@@ -5699,7 +6362,7 @@ function validateTaskExpectationMin(unit, min, pipelineIdentification) {
 /**
  * Validates the maximum expectation bound for one unit.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal utility of `validatePipelineTasks`
  */
 function validateTaskExpectationMax(unit, max, pipelineIdentification) {
     if (max === undefined || max > 0) {
@@ -5711,123 +6374,62 @@ function validateTaskExpectationMax(unit, max, pipelineIdentification) {
                 ${block(pipelineIdentification)}
             `));
 }
+
 /**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
- *
- * @private internal utility of `validatePipeline`
- */
-function createInitialDependencyResolutionState(pipeline) {
-    return {
-        resolvedParameterNames: createInitiallyResolvedParameterNames(pipeline),
-        unresolvedTasks: [...pipeline.tasks],
-    };
-}
-/**
- * Checks whether dependency resolution still has tasks left to process.
- *
- * @private internal utility of `validatePipeline`
- */
-function hasUnresolvedTasks({ unresolvedTasks }) {
-    return unresolvedTasks.length > 0;
-}
-/**
- * Resolves the next batch of currently satisfiable tasks.
+ * Validates PipelineJson if it is logically valid
  *
- * @private internal utility of `validatePipeline`
- */
-function resolveNextDependencyResolutionState(dependencyResolutionState, pipelineIdentification) {
-    const currentlyResolvedTasks = getCurrentlyResolvedTasks(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames);
-    if (currentlyResolvedTasks.length === 0) {
-        throw createUnresolvedTasksError(dependencyResolutionState.unresolvedTasks, dependencyResolutionState.resolvedParameterNames, pipelineIdentification);
-    }
-    return {
-        resolvedParameterNames: appendResolvedTaskParameterNames(dependencyResolutionState.resolvedParameterNames, currentlyResolvedTasks),
-        unresolvedTasks: dependencyResolutionState.unresolvedTasks.filter((task) => !currentlyResolvedTasks.includes(task)),
-    };
-}
-/**
- * Collects the parameter names that are already resolvable before dependency traversal starts.
+ * It checks:
+ * -   if it has correct parameters dependency
  *
- * @private internal utility of `validatePipeline`
- */
-function createInitiallyResolvedParameterNames(pipeline) {
-    let resolvedParameterNames = pipeline.parameters
-        .filter(({ isInput }) => isInput)
-        .map(({ name }) => name);
-    for (const reservedParameterName of RESERVED_PARAMETER_NAMES) {
-        resolvedParameterNames = [...resolvedParameterNames, reservedParameterName];
-    }
-    return resolvedParameterNames;
-}
-/**
- * Adds newly resolved task outputs to the resolved parameter list.
+ * It does NOT check:
+ * -   if it is valid json
+ * -   if it is meaningful
  *
- * @private internal utility of `validatePipeline`
- */
-function appendResolvedTaskParameterNames(resolvedParameterNames, currentlyResolvedTasks) {
-    return [
-        ...resolvedParameterNames,
-        ...currentlyResolvedTasks.map(({ resultingParameterName }) => resultingParameterName),
-    ];
-}
-/**
- * Selects tasks whose dependencies are already resolved.
+ * Note: [🔂] This function is idempotent.
  *
- * @private internal utility of `validatePipeline`
- */
-function getCurrentlyResolvedTasks(unresolvedTasks, resolvedParameterNames) {
-    return unresolvedTasks.filter((task) => task.dependentParameterNames.every((name) => resolvedParameterNames.includes(name)));
-}
-/**
- * Creates the unexpected loop-limit error for dependency resolution.
+ * @param pipeline valid or invalid PipelineJson
+ * @returns the same pipeline if it is logically valid
+ * @throws {PipelineLogicError} on logical error in the pipeline
  *
- * @private internal utility of `validatePipeline`
+ * @public exported from `@promptbook/core`
  */
-function createDependencyResolutionLoopLimitError(pipelineIdentification) {
-    // Note: Really UnexpectedError not LimitReachedError - this should not happen and be caught below
-    return new UnexpectedError(spaceTrim$1((block) => `
-                Loop limit reached during detection of circular dependencies in \`validatePipeline\`
+function validatePipeline(pipeline) {
+    if (IS_PIPELINE_LOGIC_VALIDATED) {
+        validatePipeline_InnerFunction(pipeline);
+    }
+    else {
+        try {
+            validatePipeline_InnerFunction(pipeline);
+        }
+        catch (error) {
+            if (!(error instanceof PipelineLogicError)) {
+                throw error;
+            }
+            console.error(spaceTrim$1((block) => `
+                        Pipeline is not valid but logic errors are temporarily disabled via \`IS_PIPELINE_LOGIC_VALIDATED\`
 
-                ${block(pipelineIdentification)}
-            `));
+                        ${block(error.message)}
+                    `));
+        }
+    }
+    return pipeline;
 }
 /**
- * Creates the detailed error for unresolved or circular task dependencies.
+ * Validates pipeline inner function.
  *
- * @private internal utility of `validatePipeline`
+ * @private internal function for `validatePipeline`
  */
-function createUnresolvedTasksError(unresolvedTasks, resolvedParameterNames, pipelineIdentification) {
-    return new PipelineLogicError(
-    // TODO: [🐎] DRY
-    spaceTrim$1((block) => `
-
-                Can not resolve some parameters:
-                Either you are using a parameter that is not defined, or there are some circular dependencies.
-
-                ${block(pipelineIdentification)}
-
-                **Can not resolve:**
-                ${block(unresolvedTasks
-        .map(({ resultingParameterName, dependentParameterNames }) => `- Parameter \`{${resultingParameterName}}\` which depends on ${dependentParameterNames
-        .map((dependentParameterName) => `\`{${dependentParameterName}}\``)
-        .join(' and ')}`)
-        .join('\n'))}
-
-                **Resolved:**
-                ${block(resolvedParameterNames
-        .filter((name) => !RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-                **Reserved (which are available):**
-                ${block(resolvedParameterNames
-        .filter((name) => RESERVED_PARAMETER_NAMES.includes(name))
-        .map((name) => `- Parameter \`{${name}}\``)
-        .join('\n'))}
-
-
-            `));
+function validatePipeline_InnerFunction(pipeline) {
+    // TODO: [🧠] Maybe test if promptbook is a promise and make specific error case for that
+    const context = createPipelineValidationContext(pipeline);
+    validatePipelineMetadata(context);
+    validatePipelineCollectionsStructure(context);
+    validatePipelineParameters(context);
+    validatePipelineTasks(context);
+    validatePipelineDependencyResolution(context);
+    // Note: Check that formfactor is corresponding to the pipeline interface
+    // TODO: !!6 Implement this
+    // pipeline.formfactorName
 }
 /**
  * TODO: [🧞‍♀️] Do not allow joker + foreach
@@ -14147,13 +14749,14 @@ class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
  * META commitment definition
  *
  * The META commitment handles all meta-information about the agent such as:
- * - META AVATAR: Sets the agent's built-in default avatar visual
+ * - META AVATAR / META VISUAL: Sets the agent's built-in default avatar visual
  * - META IMAGE: Sets the agent's avatar/profile image URL
  * - META LINK: Provides profile/source links for the person the agent models
  * - META DOMAIN: Sets the canonical custom domain/host of the agent
  * - 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,
@@ -14162,13 +14765,14 @@ class MessageSuffixCommitmentDefinition extends BaseCommitmentDefinition {
  * Example usage in agent source:
  *
  * ```book
- * META AVATAR pixel-art
+ * META VISUAL pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com
  * 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
  * ```
@@ -14202,13 +14806,14 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
 
             ## Supported META types
 
-            - **META AVATAR** - Sets the agent's built-in default avatar visual
+            - **META AVATAR** / **META VISUAL** - Sets the agent's built-in default avatar visual
             - **META IMAGE** - Sets the agent's avatar/profile image URL
             - **META LINK** - Provides profile/source links for the person the agent models
             - **META DOMAIN** - Sets the canonical custom domain/host of the agent
             - **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
@@ -14217,6 +14822,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
             - 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
@@ -14226,7 +14832,7 @@ class MetaCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`book
             Professional Assistant
 
-            META AVATAR octopus3
+            META VISUAL octopus3
             META IMAGE https://example.com/professional-avatar.jpg
             META TITLE Senior Business Consultant
             META DESCRIPTION Specialized in strategic planning and project management
@@ -17397,452 +18003,13 @@ function formatAlphaHex$1(opacity) {
         .padStart(2, '0');
 }
 
-/* eslint-disable no-magic-numbers */
-/**
- * Light direction used by the organic 3D octopus shading.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-const LIGHT_DIRECTION$3 = normalizeVector3({
-    x: 0.48,
-    y: -0.62,
-    z: 0.94,
-});
-/**
- * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-const octopus3dStableStateCache = new WeakMap();
-/**
- * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function getOctopus3dStableState(createRandom) {
-    const cached = octopus3dStableStateCache.get(createRandom);
-    if (cached !== undefined) {
-        return cached;
-    }
-    const animationRandom = createRandom('octopus3d-animation-profile');
-    const eyeRandom = createRandom('octopus3d-eye-profile');
-    const leftEyePhaseOffset = eyeRandom() * 0.6;
-    const rightEyePhaseOffset = eyeRandom() * 0.6;
-    const state = {
-        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
-        animationPhase: animationRandom() * Math.PI * 2,
-        leftEyePhaseOffset,
-        rightEyePhaseOffset,
-    };
-    octopus3dStableStateCache.set(createRandom, state);
-    return state;
-}
-/**
- * Proper 3D Octopus visual built from projected organic meshes and tentacles.
- *
- * @private built-in avatar visual
- */
-const octopus3dAvatarVisual = {
-    id: 'octopus3d',
-    title: 'Octopus 3D',
-    description: 'Proper 3D octopus portrait with a turning silhouette, expressive eyes, and depth-sorted tentacles.',
-    isAnimated: true,
-    supportsPointerTracking: true,
-    render({ context, size, palette, createRandom, timeMs, interaction }) {
-        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } = getOctopus3dStableState(createRandom);
-        const sceneCenterX = size * 0.5;
-        const sceneCenterY = size * 0.56;
-        const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
-        const mantleCenter = {
-            x: interaction.bodyOffsetX * size * 0.042 + size * morphologyProfile.body.centerXJitterRatio * 0.65,
-            y: -size * 0.09 + interaction.bodyOffsetY * size * 0.028 + bob,
-            z: interaction.intensity * size * 0.012,
-        };
-        const underbodyCenter = {
-            x: mantleCenter.x * 0.86,
-            y: mantleCenter.y + size * 0.168,
-            z: mantleCenter.z - size * 0.018,
-        };
-        const mantleRadiusX = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.horizontalStretch;
-        const mantleRadiusY = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.verticalStretch * 1.1;
-        const mantleRadiusZ = size *
-            morphologyProfile.body.bodyRadiusRatio *
-            (0.9 + (morphologyProfile.body.horizontalStretch - 1) * 0.3);
-        const underbodyRadiusX = mantleRadiusX * (0.9 + (morphologyProfile.tentacles.rootSpreadScale - 1) * 0.08);
-        const underbodyRadiusY = mantleRadiusY * (0.44 + morphologyProfile.body.lowerDropRatio * 3.1);
-        const underbodyRadiusZ = mantleRadiusZ * 0.78;
-        const bodyYaw = -0.18 +
-            Math.sin(timeMs / 2400 + animationPhase) * 0.05 +
-            interaction.bodyOffsetX * 0.18 +
-            interaction.gazeX * 0.22;
-        const bodyPitch = -0.08 +
-            Math.cos(timeMs / 2700 + animationPhase * 0.6) * 0.025 -
-            interaction.bodyOffsetY * 0.08 -
-            interaction.gazeY * 0.08;
-        const headYaw = bodyYaw - 0.04 + interaction.gazeX * 0.56;
-        const headPitch = bodyPitch - 0.02 - interaction.gazeY * 0.32;
-        const mantlePatches = resolveVisibleEllipsoidPatches({
-            center: mantleCenter,
-            radiusX: mantleRadiusX,
-            radiusY: mantleRadiusY,
-            radiusZ: mantleRadiusZ,
-            rotationX: headPitch,
-            rotationY: headYaw,
-            sceneCenterX,
-            sceneCenterY,
-            size,
-            palette,
-            verticalColorBias: 0,
-            outlineColor: `${palette.highlight}7a`,
-        });
-        const underbodyPatches = resolveVisibleEllipsoidPatches({
-            center: underbodyCenter,
-            radiusX: underbodyRadiusX,
-            radiusY: underbodyRadiusY,
-            radiusZ: underbodyRadiusZ,
-            rotationX: bodyPitch,
-            rotationY: bodyYaw,
-            sceneCenterX,
-            sceneCenterY,
-            size,
-            palette,
-            verticalColorBias: 0.18,
-            outlineColor: `${palette.shadow}8f`,
-        });
-        const tentacleStrokes = createOctopusTentacleStrokes({
-            createRandom,
-            morphologyProfile,
-            timeMs,
-            size,
-            center: underbodyCenter,
-            radiusX: underbodyRadiusX,
-            radiusY: underbodyRadiusY,
-            radiusZ: underbodyRadiusZ,
-            rotationX: bodyPitch,
-            rotationY: bodyYaw,
-            sceneCenterX,
-            sceneCenterY,
-            animationPhase,
-        });
-        const faceEyeSpacing = size * morphologyProfile.face.eyeSpacingRatio * 0.92;
-        const faceEyeYOffset = size * morphologyProfile.face.eyeCenterYOffsetRatio - mantleRadiusY * 0.02;
-        const faceEyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.82;
-        const faceEyeRadiusY = faceEyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.96;
-        const mouthHalfWidth = size * morphologyProfile.face.mouthWidthRatio * 0.92;
-        const mouthY = size * morphologyProfile.face.mouthYOffsetRatio + mantleRadiusY * 0.08;
-        drawAvatarFrame(context, size, palette);
-        drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs);
-        drawOctopus3dShadow(context, size, palette, interaction, timeMs);
-        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => !candidateTentacleStroke.isFrontFacing)) {
-            drawTentacleStroke(context, tentacleStroke, palette);
-        }
-        for (const surfacePatch of [...mantlePatches, ...underbodyPatches].sort((firstSurfacePatch, secondSurfacePatch) => firstSurfacePatch.averageDepth - secondSurfacePatch.averageDepth)) {
-            drawSurfacePatch(context, surfacePatch);
-        }
-        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => candidateTentacleStroke.isFrontFacing)) {
-            drawTentacleStroke(context, tentacleStroke, palette);
-        }
-        drawProjectedOrganicEye(context, {
-            x: -faceEyeSpacing,
-            y: faceEyeYOffset,
-            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicEye(context, {
-            x: faceEyeSpacing,
-            y: faceEyeYOffset,
-            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
-        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
-        drawProjectedOrganicMouth(context, [
-            {
-                x: -mouthHalfWidth,
-                y: mouthY,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -mouthHalfWidth, mouthY),
-            },
-            {
-                x: size * morphologyProfile.face.mouthCenterOffsetRatio,
-                y: mouthY +
-                    size * morphologyProfile.face.mouthCurveDepthRatio * 0.38 +
-                    Math.sin(timeMs / 760 + animationPhase) * size * 0.01 +
-                    interaction.gazeY * size * 0.01,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, size * morphologyProfile.face.mouthCenterOffsetRatio, mouthY),
-            },
-            {
-                x: mouthHalfWidth,
-                y: mouthY,
-                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, mouthHalfWidth, mouthY),
-            },
-        ], mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, palette, size);
-    },
-};
-/**
- * Draws the atmospheric underwater glow behind the octopus mesh.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs) {
-    const glowGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.1, sceneCenterY - size * 0.2 + interaction.gazeY * size * 0.05, size * 0.04, sceneCenterX, sceneCenterY - size * 0.04, size * 0.62);
-    glowGradient.addColorStop(0, `${palette.highlight}5c`);
-    glowGradient.addColorStop(0.36, `${palette.accent}24`);
-    glowGradient.addColorStop(1, `${palette.highlight}00`);
-    context.fillStyle = glowGradient;
-    context.fillRect(0, 0, size, size);
-    const lowerGradient = context.createRadialGradient(sceneCenterX + Math.sin(timeMs / 1700) * size * 0.05, sceneCenterY + size * 0.23, size * 0.08, sceneCenterX, sceneCenterY + size * 0.28, size * 0.5);
-    lowerGradient.addColorStop(0, `${palette.secondary}1d`);
-    lowerGradient.addColorStop(1, `${palette.secondary}00`);
-    context.fillStyle = lowerGradient;
-    context.fillRect(0, 0, size, size);
-}
-/**
- * Draws the soft ground shadow below the octopus.
- *
- * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
- * blurry ellipse without triggering a costly software rasterization pass on every frame.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawOctopus3dShadow(context, size, palette, interaction, timeMs) {
-    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
-    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
-    const rx = size * (0.18 + interaction.intensity * 0.02);
-    const ry = size * 0.06;
-    context.save();
-    context.translate(cx, cy);
-    context.scale(1, ry / rx);
-    const blurRadius = rx * 1.4;
-    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
-    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
-    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
-    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
-    shadowGradient.addColorStop(1, `${palette.shadow}00`);
-    context.fillStyle = shadowGradient;
-    context.beginPath();
-    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
-    context.fill();
-    context.restore();
-}
-/**
- * Resolves visible projected patches for one rotated ellipsoid mesh.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveVisibleEllipsoidPatches(options) {
-    const { center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, verticalColorBias, outlineColor, } = options;
-    const latitudePatchCount = 10;
-    const longitudePatchCount = 18;
-    const surfacePatches = [];
-    for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
-        const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
-        const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
-        const verticalProgress = (latitudeIndex + 0.5) / latitudePatchCount;
-        for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
-            const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
-            const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
-            const localCorners = [
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, startLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, endLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, endLongitude),
-                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, startLongitude),
-            ];
-            const transformedCorners = localCorners.map((localCorner) => transformScenePoint(localCorner, center, rotationX, rotationY));
-            const surfaceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
-            if (surfaceNormal.z <= 0.01) {
-                continue;
-            }
-            const projectedCorners = transformedCorners.map((transformedCorner) => projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY));
-            surfacePatches.push({
-                corners: projectedCorners,
-                averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
-                    transformedCorners.length,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$3), -1, 1),
-                fillStyle: resolveSurfacePatchFillStyle(palette, verticalProgress + verticalColorBias),
-                outlineColor,
-            });
-        }
-    }
-    return surfacePatches;
-}
-/**
- * Samples one point on an ellipsoid aligned to the local axes.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function sampleEllipsoidPoint(radiusX, radiusY, radiusZ, latitude, longitude) {
-    const cosineLatitude = Math.cos(latitude);
-    return {
-        x: Math.sin(longitude) * cosineLatitude * radiusX,
-        y: Math.sin(latitude) * radiusY,
-        z: Math.cos(longitude) * cosineLatitude * radiusZ,
-    };
-}
-/**
- * Resolves one base fill tone for a surface patch across the octopus body.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveSurfacePatchFillStyle(palette, verticalProgress) {
-    const clampedVerticalProgress = clampNumber$1(verticalProgress, 0, 1);
-    if (clampedVerticalProgress < 0.2) {
-        return palette.highlight;
-    }
-    if (clampedVerticalProgress < 0.45) {
-        return palette.secondary;
-    }
-    if (clampedVerticalProgress < 0.8) {
-        return palette.primary;
-    }
-    return `${palette.shadow}f2`;
-}
-/**
- * Draws one projected mesh patch with organic shading.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawSurfacePatch(context, surfacePatch) {
-    drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
-    if (surfacePatch.lightIntensity > 0) {
-        drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.15 * surfacePatch.lightIntensity})`);
-    }
-    else if (surfacePatch.lightIntensity < 0) {
-        drawProjectedQuad(context, surfacePatch.corners, `rgba(0, 0, 0, ${0.24 * Math.abs(surfacePatch.lightIntensity)})`);
-    }
-    context.save();
-    context.beginPath();
-    context.moveTo(surfacePatch.corners[0].x, surfacePatch.corners[0].y);
-    for (let cornerIndex = 1; cornerIndex < surfacePatch.corners.length; cornerIndex++) {
-        context.lineTo(surfacePatch.corners[cornerIndex].x, surfacePatch.corners[cornerIndex].y);
-    }
-    context.closePath();
-    context.strokeStyle = surfacePatch.outlineColor;
-    context.lineWidth = Math.max(1, getProjectedQuadPerimeter(surfacePatch.corners) * 0.0044);
-    context.lineJoin = 'round';
-    context.stroke();
-    context.restore();
-}
-/**
- * Creates the projected 3D tentacle strokes orbiting around the lower octopus body.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function createOctopusTentacleStrokes(options) {
-    const { createRandom, morphologyProfile, timeMs, size, center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, animationPhase, } = options;
-    return Array.from({ length: morphologyProfile.tentacles.count }, (_, tentacleIndex) => {
-        const tentacleRandom = createRandom(`octopus3d-tentacle-${tentacleIndex}`);
-        const spreadProgress = morphologyProfile.tentacles.count === 1 ? 0.5 : tentacleIndex / (morphologyProfile.tentacles.count - 1);
-        const orbitAngle = -Math.PI * 0.92 + spreadProgress * Math.PI * 1.84 + (tentacleRandom() - 0.5) * 0.16;
-        const flowLength = size * (0.19 + morphologyProfile.tentacles.flowLengthScale * 0.075 + tentacleRandom() * 0.018);
-        const lateralReach = size *
-            (0.08 + morphologyProfile.tentacles.lateralReachScale * 0.05 + Math.abs(Math.sin(orbitAngle)) * 0.018);
-        const depthReach = size * (0.028 + morphologyProfile.tentacles.tipReachScale * 0.032);
-        const sway = Math.sin(timeMs / (760 + tentacleIndex * 36) + animationPhase + tentacleRandom() * Math.PI * 2);
-        const anchorPoint = {
-            x: Math.sin(orbitAngle) * radiusX * (0.84 + tentacleRandom() * 0.08),
-            y: radiusY * (0.22 + tentacleRandom() * 0.18),
-            z: Math.cos(orbitAngle) * radiusZ * (0.72 + tentacleRandom() * 0.12),
-        };
-        const controlPointOne = {
-            x: anchorPoint.x + Math.sin(orbitAngle) * lateralReach * 0.44,
-            y: anchorPoint.y + flowLength * 0.26,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.3 + sway * size * 0.012,
-        };
-        const controlPointTwo = {
-            x: anchorPoint.x +
-                Math.sin(orbitAngle) * lateralReach * (0.82 + morphologyProfile.tentacles.swayScale * 0.12),
-            y: anchorPoint.y + flowLength * 0.66,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.72 + sway * size * 0.02,
-        };
-        const endPoint = {
-            x: anchorPoint.x +
-                Math.sin(orbitAngle) * lateralReach * (1.02 + morphologyProfile.tentacles.tipWidthScale * 0.12) +
-                sway * size * 0.028,
-            y: anchorPoint.y + flowLength,
-            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach + sway * size * 0.016,
-        };
-        const scenePoints = Array.from({ length: 12 }, (_, sampleIndex) => transformScenePoint(sampleCubicBezierPoint3D(anchorPoint, controlPointOne, controlPointTwo, endPoint, sampleIndex / 11), center, rotationX, rotationY));
-        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
-        const averageDepth = scenePoints.reduce((depthSum, scenePoint) => depthSum + scenePoint.z, 0) / scenePoints.length;
-        return {
-            projectedPoints,
-            averageDepth,
-            isFrontFacing: averageDepth >= center.z - size * 0.006,
-            baseWidth: size *
-                (0.019 +
-                    morphologyProfile.tentacles.baseWidthScale * 0.007 +
-                    tentacleRandom() * 0.003 +
-                    Math.abs(Math.sin(orbitAngle)) * 0.002),
-            tipWidth: size * (0.0046 + morphologyProfile.tentacles.tipWidthScale * 0.0018),
-            colorBias: tentacleRandom(),
-        };
-    });
-}
-/**
- * Samples one point on a cubic Bezier curve in 3D.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function sampleCubicBezierPoint3D(startPoint, controlPointOne, controlPointTwo, endPoint, progress) {
-    const inverseProgress = 1 - progress;
-    return {
-        x: inverseProgress * inverseProgress * inverseProgress * startPoint.x +
-            3 * inverseProgress * inverseProgress * progress * controlPointOne.x +
-            3 * inverseProgress * progress * progress * controlPointTwo.x +
-            progress * progress * progress * endPoint.x,
-        y: inverseProgress * inverseProgress * inverseProgress * startPoint.y +
-            3 * inverseProgress * inverseProgress * progress * controlPointOne.y +
-            3 * inverseProgress * progress * progress * controlPointTwo.y +
-            progress * progress * progress * endPoint.y,
-        z: inverseProgress * inverseProgress * inverseProgress * startPoint.z +
-            3 * inverseProgress * inverseProgress * progress * controlPointOne.z +
-            3 * inverseProgress * progress * progress * controlPointTwo.z +
-            progress * progress * progress * endPoint.z,
-    };
-}
-/**
- * Draws one projected tentacle stroke with a slim highlight ridge.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function drawTentacleStroke(context, tentacleStroke, palette) {
-    const projectedSegments = tentacleStroke.projectedPoints.length - 1;
-    for (let segmentIndex = 0; segmentIndex < projectedSegments; segmentIndex++) {
-        const startPoint = tentacleStroke.projectedPoints[segmentIndex];
-        const endPoint = tentacleStroke.projectedPoints[segmentIndex + 1];
-        const progress = segmentIndex / projectedSegments;
-        const width = tentacleStroke.baseWidth + (tentacleStroke.tipWidth - tentacleStroke.baseWidth) * progress;
-        context.beginPath();
-        context.moveTo(startPoint.x, startPoint.y);
-        context.lineTo(endPoint.x, endPoint.y);
-        context.strokeStyle = tentacleStroke.colorBias > 0.6 ? `${palette.secondary}f0` : `${palette.primary}f0`;
-        context.lineWidth = width;
-        context.lineCap = 'round';
-        context.stroke();
-        context.beginPath();
-        context.moveTo(startPoint.x, startPoint.y);
-        context.lineTo(endPoint.x, endPoint.y);
-        context.strokeStyle = tentacleStroke.isFrontFacing ? `${palette.highlight}80` : `${palette.highlight}40`;
-        context.lineWidth = Math.max(1, width * 0.34);
-        context.lineCap = 'round';
-        context.stroke();
-    }
-}
-/**
- * Resolves the front surface depth on an ellipsoid for one local face point.
- *
- * @private helper of `octopus3dAvatarVisual`
- */
-function resolveEllipsoidSurfaceDepth(radiusX, radiusY, radiusZ, x, y) {
-    const normalizedX = x / radiusX;
-    const normalizedY = y / radiusY;
-    const remainingDepthRatio = Math.max(0, 1 - normalizedX * normalizedX - normalizedY * normalizedY);
-    return Math.sqrt(remainingDepthRatio) * radiusZ;
-}
-
 /* eslint-disable no-magic-numbers */
 /**
  * Light direction used by the single-mesh octopus shading.
  *
  * @private helper of `octopus3d2AvatarVisual`
  */
-const LIGHT_DIRECTION$2 = normalizeVector3({
+const LIGHT_DIRECTION$3 = normalizeVector3({
     x: 0.38,
     y: -0.6,
     z: 0.98,
@@ -18081,7 +18248,7 @@ function resolveVisibleBlobbyOctopusPatches(options) {
                     transformedCorners[2].z +
                     transformedCorners[3].z) /
                     4,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$2), -1, 1),
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$3), -1, 1),
                 fillStyle: resolveBlobbySurfacePatchFillStyle$1(palette, verticalProgress, Math.max(0, Math.cos(centerLongitude)), resolveLowerLobeWave(centerLongitude, morphologyProfile, animationPhase, timeMs)),
                 outlineColor: verticalProgress < 0.58 ? `${palette.highlight}73` : `${palette.shadow}8a`,
             });
@@ -18196,7 +18363,7 @@ function drawBlobbySurfacePatch(context, surfacePatch) {
  *
  * @private helper of `octopus3d3AvatarVisual`
  */
-const LIGHT_DIRECTION$1 = normalizeVector3({
+const LIGHT_DIRECTION$2 = normalizeVector3({
     x: 0.34,
     y: -0.62,
     z: 1,
@@ -18503,7 +18670,7 @@ function resolveVisibleContinuousOctopusPatches(options) {
                     transformedCorners[2].z +
                     transformedCorners[3].z) /
                     4,
-                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$1), -1, 1),
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$2), -1, 1),
                 fillStyle: resolveContinuousSurfacePatchFillStyle(palette, verticalProgress, cachedCosByPatchCenterLongitude[longitudeIndex], cachedTentacleInfluencesByPatchCenterLongitude[longitudeIndex].core, cachedLobeWavesByPatchCenterLongitude[longitudeIndex]),
                 outlineColor: verticalProgress < 0.54 ? `${palette.highlight}69` : `${palette.shadow}78`,
             });
@@ -18818,7 +18985,7 @@ function smoothStep$1(edgeStart, edgeEnd, value) {
  *
  * @private helper of `octopus3d4AvatarVisual`
  */
-const LIGHT_DIRECTION = normalizeVector3({
+const LIGHT_DIRECTION$1 = normalizeVector3({
     x: 0.32,
     y: -0.66,
     z: 1,
@@ -19164,7 +19331,7 @@ function resolveVisibleBlobbyContinuousPatches(options) {
                 projectScenePoint(transformedCorners[2], size, sceneCenterX, sceneCenterY),
                 projectScenePoint(transformedCorners[3], size, sceneCenterX, sceneCenterY),
             ];
-            const lightIntensity = clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1);
+            const lightIntensity = clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION$1), -1, 1);
             const rimLightIntensity = Math.pow(clampNumber$1(dotProduct3D(surfaceNormal, RIM_LIGHT_DIRECTION), 0, 1), 2.6);
             surfacePatches.push({
                 corners: projectedCorners,
@@ -19563,6 +19730,445 @@ function formatAlphaHex(opacity) {
         .padStart(2, '0');
 }
 
+/* eslint-disable no-magic-numbers */
+/**
+ * Light direction used by the organic 3D octopus shading.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const LIGHT_DIRECTION = normalizeVector3({
+    x: 0.48,
+    y: -0.62,
+    z: 0.94,
+});
+/**
+ * Cache keyed by the `createRandom` factory reference (stable per mounted `<Avatar/>`).
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+const octopus3dStableStateCache = new WeakMap();
+/**
+ * Returns the stable per-avatar state, computing it on first access and caching for subsequent frames.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function getOctopus3dStableState(createRandom) {
+    const cached = octopus3dStableStateCache.get(createRandom);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const animationRandom = createRandom('octopus3d-animation-profile');
+    const eyeRandom = createRandom('octopus3d-eye-profile');
+    const leftEyePhaseOffset = eyeRandom() * 0.6;
+    const rightEyePhaseOffset = eyeRandom() * 0.6;
+    const state = {
+        morphologyProfile: createOctopus3MorphologyProfile(createRandom),
+        animationPhase: animationRandom() * Math.PI * 2,
+        leftEyePhaseOffset,
+        rightEyePhaseOffset,
+    };
+    octopus3dStableStateCache.set(createRandom, state);
+    return state;
+}
+/**
+ * Proper 3D Octopus visual built from projected organic meshes and tentacles.
+ *
+ * @private built-in avatar visual
+ */
+const octopus3dAvatarVisual = {
+    id: 'octopus3d',
+    title: 'Octopus 3D',
+    description: 'Proper 3D octopus portrait with a turning silhouette, expressive eyes, and depth-sorted tentacles.',
+    isAnimated: true,
+    supportsPointerTracking: true,
+    render({ context, size, palette, createRandom, timeMs, interaction }) {
+        const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset } = getOctopus3dStableState(createRandom);
+        const sceneCenterX = size * 0.5;
+        const sceneCenterY = size * 0.56;
+        const bob = Math.sin(timeMs / 920 + animationPhase) * size * 0.014;
+        const mantleCenter = {
+            x: interaction.bodyOffsetX * size * 0.042 + size * morphologyProfile.body.centerXJitterRatio * 0.65,
+            y: -size * 0.09 + interaction.bodyOffsetY * size * 0.028 + bob,
+            z: interaction.intensity * size * 0.012,
+        };
+        const underbodyCenter = {
+            x: mantleCenter.x * 0.86,
+            y: mantleCenter.y + size * 0.168,
+            z: mantleCenter.z - size * 0.018,
+        };
+        const mantleRadiusX = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.horizontalStretch;
+        const mantleRadiusY = size * morphologyProfile.body.bodyRadiusRatio * morphologyProfile.body.verticalStretch * 1.1;
+        const mantleRadiusZ = size *
+            morphologyProfile.body.bodyRadiusRatio *
+            (0.9 + (morphologyProfile.body.horizontalStretch - 1) * 0.3);
+        const underbodyRadiusX = mantleRadiusX * (0.9 + (morphologyProfile.tentacles.rootSpreadScale - 1) * 0.08);
+        const underbodyRadiusY = mantleRadiusY * (0.44 + morphologyProfile.body.lowerDropRatio * 3.1);
+        const underbodyRadiusZ = mantleRadiusZ * 0.78;
+        const bodyYaw = -0.18 +
+            Math.sin(timeMs / 2400 + animationPhase) * 0.05 +
+            interaction.bodyOffsetX * 0.18 +
+            interaction.gazeX * 0.22;
+        const bodyPitch = -0.08 +
+            Math.cos(timeMs / 2700 + animationPhase * 0.6) * 0.025 -
+            interaction.bodyOffsetY * 0.08 -
+            interaction.gazeY * 0.08;
+        const headYaw = bodyYaw - 0.04 + interaction.gazeX * 0.56;
+        const headPitch = bodyPitch - 0.02 - interaction.gazeY * 0.32;
+        const mantlePatches = resolveVisibleEllipsoidPatches({
+            center: mantleCenter,
+            radiusX: mantleRadiusX,
+            radiusY: mantleRadiusY,
+            radiusZ: mantleRadiusZ,
+            rotationX: headPitch,
+            rotationY: headYaw,
+            sceneCenterX,
+            sceneCenterY,
+            size,
+            palette,
+            verticalColorBias: 0,
+            outlineColor: `${palette.highlight}7a`,
+        });
+        const underbodyPatches = resolveVisibleEllipsoidPatches({
+            center: underbodyCenter,
+            radiusX: underbodyRadiusX,
+            radiusY: underbodyRadiusY,
+            radiusZ: underbodyRadiusZ,
+            rotationX: bodyPitch,
+            rotationY: bodyYaw,
+            sceneCenterX,
+            sceneCenterY,
+            size,
+            palette,
+            verticalColorBias: 0.18,
+            outlineColor: `${palette.shadow}8f`,
+        });
+        const tentacleStrokes = createOctopusTentacleStrokes({
+            createRandom,
+            morphologyProfile,
+            timeMs,
+            size,
+            center: underbodyCenter,
+            radiusX: underbodyRadiusX,
+            radiusY: underbodyRadiusY,
+            radiusZ: underbodyRadiusZ,
+            rotationX: bodyPitch,
+            rotationY: bodyYaw,
+            sceneCenterX,
+            sceneCenterY,
+            animationPhase,
+        });
+        const faceEyeSpacing = size * morphologyProfile.face.eyeSpacingRatio * 0.92;
+        const faceEyeYOffset = size * morphologyProfile.face.eyeCenterYOffsetRatio - mantleRadiusY * 0.02;
+        const faceEyeRadiusX = size * morphologyProfile.face.eyeRadiusXRatio * 0.82;
+        const faceEyeRadiusY = faceEyeRadiusX * morphologyProfile.face.eyeHeightRatio * 0.96;
+        const mouthHalfWidth = size * morphologyProfile.face.mouthWidthRatio * 0.92;
+        const mouthY = size * morphologyProfile.face.mouthYOffsetRatio + mantleRadiusY * 0.08;
+        drawAvatarFrame(context, size, palette);
+        drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs);
+        drawOctopus3dShadow(context, size, palette, interaction, timeMs);
+        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => !candidateTentacleStroke.isFrontFacing)) {
+            drawTentacleStroke(context, tentacleStroke, palette);
+        }
+        for (const surfacePatch of [...mantlePatches, ...underbodyPatches].sort((firstSurfacePatch, secondSurfacePatch) => firstSurfacePatch.averageDepth - secondSurfacePatch.averageDepth)) {
+            drawSurfacePatch(context, surfacePatch);
+        }
+        for (const tentacleStroke of tentacleStrokes.filter((candidateTentacleStroke) => candidateTentacleStroke.isFrontFacing)) {
+            drawTentacleStroke(context, tentacleStroke, palette);
+        }
+        drawProjectedOrganicEye(context, {
+            x: -faceEyeSpacing,
+            y: faceEyeYOffset,
+            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -faceEyeSpacing, faceEyeYOffset),
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + leftEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicEye(context, {
+            x: faceEyeSpacing,
+            y: faceEyeYOffset,
+            z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, faceEyeSpacing, faceEyeYOffset),
+        }, faceEyeRadiusX, faceEyeRadiusY, mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, size, palette, timeMs, animationPhase + 0.7 + rightEyePhaseOffset, interaction, morphologyProfile.face.eyeStyle);
+        drawProjectedOrganicMouth(context, [
+            {
+                x: -mouthHalfWidth,
+                y: mouthY,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, -mouthHalfWidth, mouthY),
+            },
+            {
+                x: size * morphologyProfile.face.mouthCenterOffsetRatio,
+                y: mouthY +
+                    size * morphologyProfile.face.mouthCurveDepthRatio * 0.38 +
+                    Math.sin(timeMs / 760 + animationPhase) * size * 0.01 +
+                    interaction.gazeY * size * 0.01,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, size * morphologyProfile.face.mouthCenterOffsetRatio, mouthY),
+            },
+            {
+                x: mouthHalfWidth,
+                y: mouthY,
+                z: resolveEllipsoidSurfaceDepth(mantleRadiusX, mantleRadiusY, mantleRadiusZ, mouthHalfWidth, mouthY),
+            },
+        ], mantleCenter, headPitch, headYaw, sceneCenterX, sceneCenterY, palette, size);
+    },
+};
+/**
+ * Draws the atmospheric underwater glow behind the octopus mesh.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawOctopus3dAtmosphere(context, size, palette, sceneCenterX, sceneCenterY, interaction, timeMs) {
+    const glowGradient = context.createRadialGradient(sceneCenterX + interaction.gazeX * size * 0.1, sceneCenterY - size * 0.2 + interaction.gazeY * size * 0.05, size * 0.04, sceneCenterX, sceneCenterY - size * 0.04, size * 0.62);
+    glowGradient.addColorStop(0, `${palette.highlight}5c`);
+    glowGradient.addColorStop(0.36, `${palette.accent}24`);
+    glowGradient.addColorStop(1, `${palette.highlight}00`);
+    context.fillStyle = glowGradient;
+    context.fillRect(0, 0, size, size);
+    const lowerGradient = context.createRadialGradient(sceneCenterX + Math.sin(timeMs / 1700) * size * 0.05, sceneCenterY + size * 0.23, size * 0.08, sceneCenterX, sceneCenterY + size * 0.28, size * 0.5);
+    lowerGradient.addColorStop(0, `${palette.secondary}1d`);
+    lowerGradient.addColorStop(1, `${palette.secondary}00`);
+    context.fillStyle = lowerGradient;
+    context.fillRect(0, 0, size, size);
+}
+/**
+ * Draws the soft ground shadow below the octopus.
+ *
+ * Uses a scaled radial gradient instead of `context.filter = 'blur()'` to approximate the
+ * blurry ellipse without triggering a costly software rasterization pass on every frame.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawOctopus3dShadow(context, size, palette, interaction, timeMs) {
+    const cx = size * 0.5 + interaction.gazeX * size * 0.04;
+    const cy = size * 0.87 + Math.sin(timeMs / 920) * size * 0.008;
+    const rx = size * (0.18 + interaction.intensity * 0.02);
+    const ry = size * 0.06;
+    context.save();
+    context.translate(cx, cy);
+    context.scale(1, ry / rx);
+    const blurRadius = rx * 1.4;
+    const shadowGradient = context.createRadialGradient(0, 0, 0, 0, 0, blurRadius);
+    shadowGradient.addColorStop(0, `${palette.shadow}7a`);
+    shadowGradient.addColorStop(0.45, `${palette.shadow}44`);
+    shadowGradient.addColorStop(0.8, `${palette.shadow}1a`);
+    shadowGradient.addColorStop(1, `${palette.shadow}00`);
+    context.fillStyle = shadowGradient;
+    context.beginPath();
+    context.arc(0, 0, blurRadius, 0, Math.PI * 2);
+    context.fill();
+    context.restore();
+}
+/**
+ * Resolves visible projected patches for one rotated ellipsoid mesh.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveVisibleEllipsoidPatches(options) {
+    const { center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, size, palette, verticalColorBias, outlineColor, } = options;
+    const latitudePatchCount = 10;
+    const longitudePatchCount = 18;
+    const surfacePatches = [];
+    for (let latitudeIndex = 0; latitudeIndex < latitudePatchCount; latitudeIndex++) {
+        const startLatitude = -Math.PI / 2 + (latitudeIndex / latitudePatchCount) * Math.PI;
+        const endLatitude = -Math.PI / 2 + ((latitudeIndex + 1) / latitudePatchCount) * Math.PI;
+        const verticalProgress = (latitudeIndex + 0.5) / latitudePatchCount;
+        for (let longitudeIndex = 0; longitudeIndex < longitudePatchCount; longitudeIndex++) {
+            const startLongitude = -Math.PI + (longitudeIndex / longitudePatchCount) * Math.PI * 2;
+            const endLongitude = -Math.PI + ((longitudeIndex + 1) / longitudePatchCount) * Math.PI * 2;
+            const localCorners = [
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, startLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, startLatitude, endLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, endLongitude),
+                sampleEllipsoidPoint(radiusX, radiusY, radiusZ, endLatitude, startLongitude),
+            ];
+            const transformedCorners = localCorners.map((localCorner) => transformScenePoint(localCorner, center, rotationX, rotationY));
+            const surfaceNormal = normalizeVector3(crossProduct3D(subtractPoint3D(transformedCorners[1], transformedCorners[0]), subtractPoint3D(transformedCorners[2], transformedCorners[0])));
+            if (surfaceNormal.z <= 0.01) {
+                continue;
+            }
+            const projectedCorners = transformedCorners.map((transformedCorner) => projectScenePoint(transformedCorner, size, sceneCenterX, sceneCenterY));
+            surfacePatches.push({
+                corners: projectedCorners,
+                averageDepth: transformedCorners.reduce((depthSum, transformedCorner) => depthSum + transformedCorner.z, 0) /
+                    transformedCorners.length,
+                lightIntensity: clampNumber$1(dotProduct3D(surfaceNormal, LIGHT_DIRECTION), -1, 1),
+                fillStyle: resolveSurfacePatchFillStyle(palette, verticalProgress + verticalColorBias),
+                outlineColor,
+            });
+        }
+    }
+    return surfacePatches;
+}
+/**
+ * Samples one point on an ellipsoid aligned to the local axes.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function sampleEllipsoidPoint(radiusX, radiusY, radiusZ, latitude, longitude) {
+    const cosineLatitude = Math.cos(latitude);
+    return {
+        x: Math.sin(longitude) * cosineLatitude * radiusX,
+        y: Math.sin(latitude) * radiusY,
+        z: Math.cos(longitude) * cosineLatitude * radiusZ,
+    };
+}
+/**
+ * Resolves one base fill tone for a surface patch across the octopus body.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveSurfacePatchFillStyle(palette, verticalProgress) {
+    const clampedVerticalProgress = clampNumber$1(verticalProgress, 0, 1);
+    if (clampedVerticalProgress < 0.2) {
+        return palette.highlight;
+    }
+    if (clampedVerticalProgress < 0.45) {
+        return palette.secondary;
+    }
+    if (clampedVerticalProgress < 0.8) {
+        return palette.primary;
+    }
+    return `${palette.shadow}f2`;
+}
+/**
+ * Draws one projected mesh patch with organic shading.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawSurfacePatch(context, surfacePatch) {
+    drawProjectedQuad(context, surfacePatch.corners, surfacePatch.fillStyle);
+    if (surfacePatch.lightIntensity > 0) {
+        drawProjectedQuad(context, surfacePatch.corners, `rgba(255, 255, 255, ${0.15 * surfacePatch.lightIntensity})`);
+    }
+    else if (surfacePatch.lightIntensity < 0) {
+        drawProjectedQuad(context, surfacePatch.corners, `rgba(0, 0, 0, ${0.24 * Math.abs(surfacePatch.lightIntensity)})`);
+    }
+    context.save();
+    context.beginPath();
+    context.moveTo(surfacePatch.corners[0].x, surfacePatch.corners[0].y);
+    for (let cornerIndex = 1; cornerIndex < surfacePatch.corners.length; cornerIndex++) {
+        context.lineTo(surfacePatch.corners[cornerIndex].x, surfacePatch.corners[cornerIndex].y);
+    }
+    context.closePath();
+    context.strokeStyle = surfacePatch.outlineColor;
+    context.lineWidth = Math.max(1, getProjectedQuadPerimeter(surfacePatch.corners) * 0.0044);
+    context.lineJoin = 'round';
+    context.stroke();
+    context.restore();
+}
+/**
+ * Creates the projected 3D tentacle strokes orbiting around the lower octopus body.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function createOctopusTentacleStrokes(options) {
+    const { createRandom, morphologyProfile, timeMs, size, center, radiusX, radiusY, radiusZ, rotationX, rotationY, sceneCenterX, sceneCenterY, animationPhase, } = options;
+    return Array.from({ length: morphologyProfile.tentacles.count }, (_, tentacleIndex) => {
+        const tentacleRandom = createRandom(`octopus3d-tentacle-${tentacleIndex}`);
+        const spreadProgress = morphologyProfile.tentacles.count === 1 ? 0.5 : tentacleIndex / (morphologyProfile.tentacles.count - 1);
+        const orbitAngle = -Math.PI * 0.92 + spreadProgress * Math.PI * 1.84 + (tentacleRandom() - 0.5) * 0.16;
+        const flowLength = size * (0.19 + morphologyProfile.tentacles.flowLengthScale * 0.075 + tentacleRandom() * 0.018);
+        const lateralReach = size *
+            (0.08 + morphologyProfile.tentacles.lateralReachScale * 0.05 + Math.abs(Math.sin(orbitAngle)) * 0.018);
+        const depthReach = size * (0.028 + morphologyProfile.tentacles.tipReachScale * 0.032);
+        const sway = Math.sin(timeMs / (760 + tentacleIndex * 36) + animationPhase + tentacleRandom() * Math.PI * 2);
+        const anchorPoint = {
+            x: Math.sin(orbitAngle) * radiusX * (0.84 + tentacleRandom() * 0.08),
+            y: radiusY * (0.22 + tentacleRandom() * 0.18),
+            z: Math.cos(orbitAngle) * radiusZ * (0.72 + tentacleRandom() * 0.12),
+        };
+        const controlPointOne = {
+            x: anchorPoint.x + Math.sin(orbitAngle) * lateralReach * 0.44,
+            y: anchorPoint.y + flowLength * 0.26,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.3 + sway * size * 0.012,
+        };
+        const controlPointTwo = {
+            x: anchorPoint.x +
+                Math.sin(orbitAngle) * lateralReach * (0.82 + morphologyProfile.tentacles.swayScale * 0.12),
+            y: anchorPoint.y + flowLength * 0.66,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach * 0.72 + sway * size * 0.02,
+        };
+        const endPoint = {
+            x: anchorPoint.x +
+                Math.sin(orbitAngle) * lateralReach * (1.02 + morphologyProfile.tentacles.tipWidthScale * 0.12) +
+                sway * size * 0.028,
+            y: anchorPoint.y + flowLength,
+            z: anchorPoint.z + Math.cos(orbitAngle) * depthReach + sway * size * 0.016,
+        };
+        const scenePoints = Array.from({ length: 12 }, (_, sampleIndex) => transformScenePoint(sampleCubicBezierPoint3D(anchorPoint, controlPointOne, controlPointTwo, endPoint, sampleIndex / 11), center, rotationX, rotationY));
+        const projectedPoints = scenePoints.map((scenePoint) => projectScenePoint(scenePoint, size, sceneCenterX, sceneCenterY));
+        const averageDepth = scenePoints.reduce((depthSum, scenePoint) => depthSum + scenePoint.z, 0) / scenePoints.length;
+        return {
+            projectedPoints,
+            averageDepth,
+            isFrontFacing: averageDepth >= center.z - size * 0.006,
+            baseWidth: size *
+                (0.019 +
+                    morphologyProfile.tentacles.baseWidthScale * 0.007 +
+                    tentacleRandom() * 0.003 +
+                    Math.abs(Math.sin(orbitAngle)) * 0.002),
+            tipWidth: size * (0.0046 + morphologyProfile.tentacles.tipWidthScale * 0.0018),
+            colorBias: tentacleRandom(),
+        };
+    });
+}
+/**
+ * Samples one point on a cubic Bezier curve in 3D.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function sampleCubicBezierPoint3D(startPoint, controlPointOne, controlPointTwo, endPoint, progress) {
+    const inverseProgress = 1 - progress;
+    return {
+        x: inverseProgress * inverseProgress * inverseProgress * startPoint.x +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.x +
+            3 * inverseProgress * progress * progress * controlPointTwo.x +
+            progress * progress * progress * endPoint.x,
+        y: inverseProgress * inverseProgress * inverseProgress * startPoint.y +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.y +
+            3 * inverseProgress * progress * progress * controlPointTwo.y +
+            progress * progress * progress * endPoint.y,
+        z: inverseProgress * inverseProgress * inverseProgress * startPoint.z +
+            3 * inverseProgress * inverseProgress * progress * controlPointOne.z +
+            3 * inverseProgress * progress * progress * controlPointTwo.z +
+            progress * progress * progress * endPoint.z,
+    };
+}
+/**
+ * Draws one projected tentacle stroke with a slim highlight ridge.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function drawTentacleStroke(context, tentacleStroke, palette) {
+    const projectedSegments = tentacleStroke.projectedPoints.length - 1;
+    for (let segmentIndex = 0; segmentIndex < projectedSegments; segmentIndex++) {
+        const startPoint = tentacleStroke.projectedPoints[segmentIndex];
+        const endPoint = tentacleStroke.projectedPoints[segmentIndex + 1];
+        const progress = segmentIndex / projectedSegments;
+        const width = tentacleStroke.baseWidth + (tentacleStroke.tipWidth - tentacleStroke.baseWidth) * progress;
+        context.beginPath();
+        context.moveTo(startPoint.x, startPoint.y);
+        context.lineTo(endPoint.x, endPoint.y);
+        context.strokeStyle = tentacleStroke.colorBias > 0.6 ? `${palette.secondary}f0` : `${palette.primary}f0`;
+        context.lineWidth = width;
+        context.lineCap = 'round';
+        context.stroke();
+        context.beginPath();
+        context.moveTo(startPoint.x, startPoint.y);
+        context.lineTo(endPoint.x, endPoint.y);
+        context.strokeStyle = tentacleStroke.isFrontFacing ? `${palette.highlight}80` : `${palette.highlight}40`;
+        context.lineWidth = Math.max(1, width * 0.34);
+        context.lineCap = 'round';
+        context.stroke();
+    }
+}
+/**
+ * Resolves the front surface depth on an ellipsoid for one local face point.
+ *
+ * @private helper of `octopus3dAvatarVisual`
+ */
+function resolveEllipsoidSurfaceDepth(radiusX, radiusY, radiusZ, x, y) {
+    const normalizedX = x / radiusX;
+    const normalizedY = y / radiusY;
+    const remainingDepthRatio = Math.max(0, 1 - normalizedX * normalizedX - normalizedY * normalizedY);
+    return Math.sqrt(remainingDepthRatio) * radiusZ;
+}
+
 /* eslint-disable no-magic-numbers */
 /**
  * Octopus avatar visual.
@@ -20383,14 +20989,14 @@ function resolveAvatarVisualId(value) {
 /**
  * META AVATAR commitment definition
  *
- * The `META AVATAR` commitment sets the built-in default avatar visual used when
- * the agent does not provide an explicit `META IMAGE`.
+ * The `META AVATAR` and `META VISUAL` commitments set the built-in default avatar visual
+ * used when the agent does not provide an explicit `META IMAGE`.
  *
  * @private [🪔] Maybe export the commitments through some package
  */
 class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
-    constructor() {
-        super('META AVATAR');
+    constructor(type = 'META AVATAR') {
+        super(type);
     }
     /**
      * Short one-line description of META AVATAR.
@@ -20410,14 +21016,15 @@ class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
     get documentation() {
         const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
         return spaceTrim$1(`
-            # META AVATAR
+            # ${this.type}
 
             Sets the built-in avatar visual used for the agent when no explicit \`META IMAGE\` is provided.
+            \`META AVATAR\` and \`META VISUAL\` are equivalent.
 
             ## Key aspects
 
             - Does not modify the agent's behavior or responses.
-            - Only one \`META AVATAR\` should be used per agent.
+            - Only one \`META AVATAR\` or \`META VISUAL\` should be used per agent.
             - If multiple are specified, the last one takes precedence.
             - Values are matched case-insensitively and spaces, hyphens, and underscores are normalized.
             - Supported visuals are derived from the shared avatar registry: ${supportedVisuals}.
@@ -20432,15 +21039,15 @@ class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition {
             \`\`\`
 
             \`\`\`book
-            Orb Assistant
+            Minecraft Assistant
 
-            META AVATAR orb
+            META VISUAL Minecraft2
             GOAL Answer in a calm and focused way.
             \`\`\`
         `);
     }
     applyToAgentModelRequirements(requirements, content) {
-        // META AVATAR doesn't modify the system message or model requirements.
+        // META AVATAR and META VISUAL don't modify the system message or model requirements.
         // It's handled separately in the parsing logic for profile avatar resolution.
         return requirements;
     }
@@ -21014,6 +21621,68 @@ class MetaLinkCommitmentDefinition extends BaseCommitmentDefinition {
 }
 // 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$1(`
+            # 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.
  *
@@ -23092,6 +23761,7 @@ class UseBrowserCommitmentDefinition extends BaseCommitmentDefinition {
               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
@@ -29628,6 +30298,7 @@ const COMMITMENT_REGISTRY = [
     new ActionCommitmentDefinition('ACTIONS'),
     new ComponentCommitmentDefinition(),
     new MetaAvatarCommitmentDefinition(),
+    new MetaAvatarCommitmentDefinition('META VISUAL'),
     new MetaImageCommitmentDefinition(),
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),
@@ -29635,6 +30306,7 @@ const COMMITMENT_REGISTRY = [
     new MetaDomainCommitmentDefinition(),
     new MetaDisclaimerCommitmentDefinition(),
     new MetaInputPlaceholderCommitmentDefinition(),
+    new MetaThinkingMessageCommitmentDefinition(),
     new MetaVisibilityCommitmentDefinition(),
     new MetaCommitmentDefinition(),
     new MetaVoiceCommitmentDefinition(),
@@ -30979,12 +31651,14 @@ function hasHttpProtocol(value) {
  */
 const META_COMMITMENT_APPLIERS = {
     'META AVATAR': applyMetaAvatarContent,
+    'META VISUAL': applyMetaAvatarContent,
     'META LINK': applyMetaLinkContent,
     'META DOMAIN': applyMetaDomainContent,
     'META IMAGE': applyMetaImageContent,
     'META DESCRIPTION': applyMetaDescriptionContent,
     'META DISCLAIMER': applyMetaDisclaimerContent,
     'META INPUT PLACEHOLDER': applyMetaInputPlaceholderContent,
+    'META THINKING MESSAGE': applyMetaThinkingMessageContent,
     'MESSAGE SUFFIX': applyMessageSuffixContent,
     'META COLOR': applyMetaColorContent,
     'META FONT': applyMetaFontContent,
@@ -31027,7 +31701,7 @@ function applyGenericMetaCommitment(state, content) {
     state.meta[metaType] = metaValue;
 }
 /**
- * Applies META AVATAR content into the canonical `meta.avatar` field.
+ * Applies META AVATAR / META VISUAL content into the canonical `meta.avatar` field.
  */
 function applyMetaAvatarContent(state, content) {
     const avatarVisualId = resolveAvatarVisualId(content);
@@ -31075,6 +31749,16 @@ function applyMetaDisclaimerContent(state, content) {
 function applyMetaInputPlaceholderContent(state, content) {
     state.meta.inputPlaceholder = spaceTrim$1(content);
 }
+/**
+ * Applies one META THINKING MESSAGE content block into the custom thinking-message variants.
+ */
+function applyMetaThinkingMessageContent(state, content) {
+    const thinkingMessage = spaceTrim$1(content);
+    if (!thinkingMessage) {
+        return;
+    }
+    state.thinkingMessages = [...(state.thinkingMessages || []), thinkingMessage];
+}
 /**
  * Applies MESSAGE SUFFIX content into the canonical `meta.messageSuffix` field.
  */
@@ -31443,6 +32127,7 @@ function extractParsedAgentProfile(commitments) {
         capabilities: [],
         samples: [],
         knowledgeSources: [],
+        thinkingMessages: [],
         pendingUserMessage: null,
         knownKnowledgeSourceUrls: new Set(),
     };
@@ -31455,6 +32140,7 @@ function extractParsedAgentProfile(commitments) {
         capabilities: state.capabilities,
         samples: state.samples,
         knowledgeSources: state.knowledgeSources,
+        thinkingMessages: state.thinkingMessages,
     };
 }
 /**
@@ -31494,6 +32180,7 @@ function parseAgentSource(agentSource) {
         permanentId: parsedProfile.meta.id,
         personaDescription,
         initialMessage,
+        thinkingMessages: parsedProfile.thinkingMessages,
         meta: parsedProfile.meta,
         links: parsedProfile.links,
         parameters: parseParameters(agentSource),
@@ -32091,6 +32778,78 @@ function normalizeCliAgentFileSegment(value) {
         .replace(/^[._-]+|[._-]+$/gu, '');
 }
 
+/**
+ * Helper of usage compute
+ *
+ * @param content the content of prompt or response
+ * @returns part of UsageCounts
+ *
+ * @private internal utility of LlmExecutionTools
+ */
+function computeUsageCounts(content) {
+    return {
+        charactersCount: { value: countCharacters(content) },
+        wordsCount: { value: countWords(content) },
+        sentencesCount: { value: countSentences(content) },
+        linesCount: { value: countLines(content) },
+        paragraphsCount: { value: countParagraphs(content) },
+        pagesCount: { value: countPages(content) },
+    };
+}
+
+/**
+ * Computes the usage of the OpenAI API based on the response from OpenAI
+ *
+ * @param promptContent The content of the prompt
+ * @param resultContent The content of the result (for embedding prompts or failed prompts pass empty string)
+ * @param rawResponse The raw response from OpenAI API
+ * @param duration The duration of the execution
+ * @throws {PipelineExecutionError} If the usage is not defined in the response from OpenAI
+ *
+ * @private internal utility of `OpenAiExecutionTools`
+ */
+function computeOpenAiUsage(promptContent, // <- Note: Intentionally using [] to access type properties to bring jsdoc from Prompt/PromptResult to consumer
+resultContent, rawResponse, duration = ZERO_VALUE) {
+    var _a, _b;
+    if (rawResponse.usage === undefined) {
+        throw new PipelineExecutionError('The usage is not defined in the response from OpenAI');
+    }
+    if (((_a = rawResponse.usage) === null || _a === void 0 ? void 0 : _a.prompt_tokens) === undefined) {
+        throw new PipelineExecutionError('In OpenAI response `usage.prompt_tokens` not defined');
+    }
+    const inputTokens = rawResponse.usage.prompt_tokens;
+    const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
+    let isUncertain = false;
+    let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
+    if (modelInfo === undefined) {
+        // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
+        modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
+        if (modelInfo !== undefined) {
+            isUncertain = true;
+        }
+    }
+    let price;
+    if (modelInfo === undefined || modelInfo.pricing === undefined) {
+        price = uncertainNumber();
+    }
+    else {
+        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
+    }
+    return {
+        price,
+        duration,
+        input: {
+            tokensCount: uncertainNumber(rawResponse.usage.prompt_tokens),
+            ...computeUsageCounts(promptContent),
+        },
+        output: {
+            tokensCount: uncertainNumber(outputTokens),
+            ...computeUsageCounts(resultContent),
+        },
+    };
+}
+// TODO: [🤝] DRY Maybe some common abstraction between `computeOpenAiUsage` and `computeAnthropicClaudeUsage`
+
 /**
  * Simple wrapper `new Date().toISOString()`
  *
@@ -32499,78 +33258,6 @@ class OpenAiAgentKitExecutionToolsToolBuilder {
     }
 }
 
-/**
- * Helper of usage compute
- *
- * @param content the content of prompt or response
- * @returns part of UsageCounts
- *
- * @private internal utility of LlmExecutionTools
- */
-function computeUsageCounts(content) {
-    return {
-        charactersCount: { value: countCharacters(content) },
-        wordsCount: { value: countWords(content) },
-        sentencesCount: { value: countSentences(content) },
-        linesCount: { value: countLines(content) },
-        paragraphsCount: { value: countParagraphs(content) },
-        pagesCount: { value: countPages(content) },
-    };
-}
-
-/**
- * Computes the usage of the OpenAI API based on the response from OpenAI
- *
- * @param promptContent The content of the prompt
- * @param resultContent The content of the result (for embedding prompts or failed prompts pass empty string)
- * @param rawResponse The raw response from OpenAI API
- * @param duration The duration of the execution
- * @throws {PipelineExecutionError} If the usage is not defined in the response from OpenAI
- *
- * @private internal utility of `OpenAiExecutionTools`
- */
-function computeOpenAiUsage(promptContent, // <- Note: Intentionally using [] to access type properties to bring jsdoc from Prompt/PromptResult to consumer
-resultContent, rawResponse, duration = ZERO_VALUE) {
-    var _a, _b;
-    if (rawResponse.usage === undefined) {
-        throw new PipelineExecutionError('The usage is not defined in the response from OpenAI');
-    }
-    if (((_a = rawResponse.usage) === null || _a === void 0 ? void 0 : _a.prompt_tokens) === undefined) {
-        throw new PipelineExecutionError('In OpenAI response `usage.prompt_tokens` not defined');
-    }
-    const inputTokens = rawResponse.usage.prompt_tokens;
-    const outputTokens = ((_b = rawResponse.usage) === null || _b === void 0 ? void 0 : _b.completion_tokens) || 0;
-    let isUncertain = false;
-    let modelInfo = OPENAI_MODELS.find((model) => model.modelName === rawResponse.model);
-    if (modelInfo === undefined) {
-        // Note: Model is not in the list of known models, fallback to the family of the models and mark price as uncertain
-        modelInfo = OPENAI_MODELS.find((model) => (rawResponse.model || SALT_NONCE).startsWith(model.modelName));
-        if (modelInfo !== undefined) {
-            isUncertain = true;
-        }
-    }
-    let price;
-    if (modelInfo === undefined || modelInfo.pricing === undefined) {
-        price = uncertainNumber();
-    }
-    else {
-        price = uncertainNumber(inputTokens * modelInfo.pricing.prompt + outputTokens * modelInfo.pricing.output, isUncertain);
-    }
-    return {
-        price,
-        duration,
-        input: {
-            tokensCount: uncertainNumber(rawResponse.usage.prompt_tokens),
-            ...computeUsageCounts(promptContent),
-        },
-        output: {
-            tokensCount: uncertainNumber(outputTokens),
-            ...computeUsageCounts(resultContent),
-        },
-    };
-}
-// TODO: [🤝] DRY Maybe some common abstraction between `computeOpenAiUsage` and `computeAnthropicClaudeUsage`
-
 /**
  * Finds the best hardcoded-model match for one API-listed model identifier.
  */
@@ -42930,7 +43617,7 @@ async function locateAppOnWindows({ appName, windowsSuffix, }) {
  *
  * @private within the repository
  */
-function locateApp(options) {
+async function locateApp(options) {
     if (!$isRunningInNode()) {
         throw new EnvironmentMismatchError('Locating apps works only in Node.js environment');
     }
@@ -43028,18 +43715,6 @@ async function $provideExecutablesForNode(options) {
 const $llmToolsMetadataRegister = new $Register('llm_tools_metadata');
 // TODO: [®] DRY Register logic
 
-/**
- * Register for LLM tools.
- *
- * Note: `$` is used to indicate that this interacts with the global scope
- *
- * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
- *
- * @public exported from `@promptbook/core`
- */
-const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
-// TODO: [®] DRY Register logic
-
 /**
  * Path to the `.env` file which was used to configure LLM tools
  *
@@ -43047,61 +43722,53 @@ const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
  */
 let $usedEnvFilename = null;
 /**
- * Pass the `.env` file which was used to configure LLM tools
- *
- * Note: `$` is used to indicate that this variable is making side effect
- *
- * @private internal log of `$provideLlmToolsConfigurationFromEnv` and `$registeredLlmToolsMessage`
- */
-function $setUsedEnvFilename(filepath) {
-    $usedEnvFilename = filepath;
-}
-/**
- * Creates a message with all registered LLM tools
- *
- * Note: This function is used to create a (error) message when there is no constructor for some LLM provider
- *
- * @private internal function of `createLlmToolsFromConfiguration` and `$provideLlmToolsFromEnv`
- */
-function $registeredLlmToolsMessage() {
-    const registeredLlmToolsMessageContext = createRegisteredLlmToolsMessageContext();
-    if (registeredLlmToolsMessageContext.llmToolStatuses.length === 0) {
-        return renderNoRegisteredLlmToolsMessage(registeredLlmToolsMessageContext.usedEnvMessage);
-    }
-    return renderRegisteredLlmToolsMessage(registeredLlmToolsMessageContext);
-}
-/**
- * Collects all state needed to render the provider summary.
+ * Shared state for the `.env` file used to configure LLM tools.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private internal state of `$registeredLlmToolsMessage`
  */
-function createRegisteredLlmToolsMessageContext() {
-    const isRunningInNode = $isRunningInNode();
-    const env = getAvailableEnvironmentVariables(isRunningInNode);
-    const registeredLlmToolRegisters = getRegisteredLlmToolRegisters();
-    return {
-        env,
-        llmToolStatuses: listRegisteredLlmToolStatuses(registeredLlmToolRegisters, env),
-        usedEnvMessage: createUsedEnvMessage(),
-        isRunningInNode,
-    };
-}
+const USED_ENV_FILENAME = {
+    set(filepath) {
+        $usedEnvFilename = filepath;
+    },
+    createMessage() {
+        return $usedEnvFilename === null
+            ? `Unknown \`.env\` file`
+            : spaceTrim$1(`
+                  Used \`.env\` file:
+                  ${$usedEnvFilename}
+              `);
+    },
+};
+
 /**
  * Reads environment variables relevant for provider configuration.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function getAvailableEnvironmentVariables(isRunningInNode) {
+function getAvailableRegisteredLlmToolsEnvironmentVariables(isRunningInNode) {
     if (isRunningInNode) {
         return process.env;
         // <- TODO: [⚛] Some DRY way how to get to `process.env` and pass it into functions - ACRY search for `env`
     }
     return {};
 }
+
+/**
+ * Register for LLM tools.
+ *
+ * Note: `$` is used to indicate that this interacts with the global scope
+ *
+ * @singleton Only one instance of each register is created per build, but there can be more instances across different builds or environments.
+ *
+ * @public exported from `@promptbook/core`
+ */
+const $llmToolsRegister = new $Register('llm_execution_tools_constructors');
+// TODO: [®] DRY Register logic
+
 /**
  * Takes stable snapshots of both LLM provider registers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function getRegisteredLlmToolRegisters() {
     return {
@@ -43109,62 +43776,30 @@ function getRegisteredLlmToolRegisters() {
         registeredTools: $llmToolsRegister.list(),
     };
 }
-/**
- * Lists provider entries enriched with installation and configuration state.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function listRegisteredLlmToolStatuses({ registeredMetadata, registeredTools }, env) {
-    return listRegisteredLlmToolEntries(registeredMetadata, registeredTools).map((registeredLlmToolEntry) => createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env }));
-}
-/**
- * Merges provider entries from the metadata and constructor registers.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function listRegisteredLlmToolEntries(registeredMetadata, registeredTools) {
-    const registeredLlmToolEntries = new Map();
-    for (const { title, packageName, className, envVariables } of registeredMetadata) {
-        addRegisteredLlmToolEntry(registeredLlmToolEntries, { title, packageName, className, envVariables });
-    }
-    for (const { packageName, className } of registeredTools) {
-        addRegisteredLlmToolEntry(registeredLlmToolEntries, { packageName, className });
-    }
-    return [...registeredLlmToolEntries.values()];
-}
-/**
- * Adds a provider entry only when the provider is not already present.
- *
- * @private internal function of `$registeredLlmToolsMessage`
- */
-function addRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
-    const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
-    if (registeredLlmToolEntries.has(registeredLlmToolEntryKey)) {
-        return;
-    }
-    registeredLlmToolEntries.set(registeredLlmToolEntryKey, registeredLlmToolEntry);
-}
+
 /**
  * Creates a deduplication key for a provider entry.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolEntryKey({ packageName, className }) {
     return `${packageName}::${className}`;
 }
+
 /**
  * Checks whether the given provider entry already exists in the target register list.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function hasRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
     const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
     return registeredLlmToolEntries.some((listedRegisteredLlmToolEntry) => createRegisteredLlmToolEntryKey(listedRegisteredLlmToolEntry) === registeredLlmToolEntryKey);
 }
+
 /**
  * Builds the runtime status for one provider entry.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env, }) {
     const availabilityStatus = createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, registeredMetadata, registeredTools);
@@ -43178,7 +43813,7 @@ function createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetad
 /**
  * Resolves whether the provider has metadata and a registered constructor.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, registeredMetadata, registeredTools) {
     return {
@@ -43189,7 +43824,7 @@ function createRegisteredLlmToolAvailabilityStatus(registeredLlmToolEntry, regis
 /**
  * Resolves whether the provider has enough environment variables to be configured.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function createRegisteredLlmToolConfigurationStatus({ envVariables }, env) {
     return {
@@ -43200,7 +43835,7 @@ function createRegisteredLlmToolConfigurationStatus({ envVariables }, env) {
 /**
  * Checks whether all required environment variables are present for a provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function isRegisteredLlmToolFullyConfigured(envVariables, env) {
     if (envVariables === undefined || envVariables === null) {
@@ -43211,7 +43846,7 @@ function isRegisteredLlmToolFullyConfigured(envVariables, env) {
 /**
  * Checks whether at least one required environment variable is present for a provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
 function isRegisteredLlmToolPartiallyConfigured(envVariables, env) {
     if (envVariables === undefined || envVariables === null) {
@@ -43219,109 +43854,128 @@ function isRegisteredLlmToolPartiallyConfigured(envVariables, env) {
     }
     return envVariables.some((envVariableName) => env[envVariableName] !== undefined);
 }
+
 /**
- * Renders the fallback message for environments with no registered providers.
+ * Merges provider entries from the metadata and constructor registers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderNoRegisteredLlmToolsMessage(usedEnvMessage) {
-    return spaceTrim$1((block) => `
-            No LLM providers are available.
-
-            ${block(usedEnvMessage)}
-      `);
+function listRegisteredLlmToolEntries(registeredMetadata, registeredTools) {
+    const registeredLlmToolEntries = new Map();
+    for (const { title, packageName, className, envVariables } of registeredMetadata) {
+        addRegisteredLlmToolEntry(registeredLlmToolEntries, { title, packageName, className, envVariables });
+    }
+    for (const { packageName, className } of registeredTools) {
+        addRegisteredLlmToolEntry(registeredLlmToolEntries, { packageName, className });
+    }
+    return [...registeredLlmToolEntries.values()];
 }
 /**
- * Renders the full provider status summary.
+ * Adds a provider entry only when the provider is not already present.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderRegisteredLlmToolsMessage({ env, llmToolStatuses, usedEnvMessage, isRunningInNode, }) {
-    return spaceTrim$1((block) => `
-
-            ${block(usedEnvMessage)}
-
-            Relevant environment variables:
-            ${block(renderRelevantEnvironmentVariables(env, llmToolStatuses))}
-
-            Available LLM providers are:
-            ${block(renderAvailableProviders(llmToolStatuses, env, isRunningInNode))}
-        `);
+function addRegisteredLlmToolEntry(registeredLlmToolEntries, registeredLlmToolEntry) {
+    const registeredLlmToolEntryKey = createRegisteredLlmToolEntryKey(registeredLlmToolEntry);
+    if (registeredLlmToolEntries.has(registeredLlmToolEntryKey)) {
+        return;
+    }
+    registeredLlmToolEntries.set(registeredLlmToolEntryKey, registeredLlmToolEntry);
 }
+
 /**
- * Renders the list of environment variables used by at least one registered provider.
+ * Lists provider entries enriched with installation and configuration state.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderRelevantEnvironmentVariables(env, llmToolStatuses) {
-    return listRelevantEnvironmentVariables(env, llmToolStatuses)
-        .map((envVariableName) => `- \`${envVariableName}\``)
-        .join('\n');
+function listRegisteredLlmToolStatuses({ registeredMetadata, registeredTools }, env) {
+    return listRegisteredLlmToolEntries(registeredMetadata, registeredTools).map((registeredLlmToolEntry) => createRegisteredLlmToolStatus({ registeredLlmToolEntry, registeredMetadata, registeredTools, env }));
 }
+
 /**
- * Lists environment variables that are both present and used by at least one provider.
+ * Collects all state needed to render the provider summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function listRelevantEnvironmentVariables(env, llmToolStatuses) {
-    return Object.keys(env).filter((envVariableName) => llmToolStatuses.some(({ envVariables }) => envVariables === null || envVariables === void 0 ? void 0 : envVariables.includes(envVariableName)));
+function createRegisteredLlmToolsMessageContext() {
+    const isRunningInNode = $isRunningInNode();
+    const env = getAvailableRegisteredLlmToolsEnvironmentVariables(isRunningInNode);
+    const registeredLlmToolRegisters = getRegisteredLlmToolRegisters();
+    return {
+        env,
+        llmToolStatuses: listRegisteredLlmToolStatuses(registeredLlmToolRegisters, env),
+        usedEnvMessage: USED_ENV_FILENAME.createMessage(),
+        isRunningInNode,
+    };
 }
+
 /**
- * Renders all provider lines in the status summary.
+ * Renders the fallback message for environments with no registered providers.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderAvailableProviders(llmToolStatuses, env, isRunningInNode) {
-    return llmToolStatuses
-        .map((llmToolStatus, index) => renderAvailableProvider(llmToolStatus, index, env, isRunningInNode))
-        .join('\n');
+function renderNoRegisteredLlmToolsMessage(usedEnvMessage) {
+    return spaceTrim$1((block) => `
+            No LLM providers are available.
+
+            ${block(usedEnvMessage)}
+      `);
 }
+
 /**
- * Renders one provider line in the status summary.
+ * Creates the configuration-status sentence for one provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function renderAvailableProvider(llmToolStatus, index, env, isRunningInNode) {
-    const providerMessage = createAvailableProviderMessage(llmToolStatus, index, env);
-    if (!isRunningInNode) {
-        return providerMessage;
+function createRegisteredLlmToolConfigurationStatusMessage({ envVariables, isFullyConfigured, isPartiallyConfigured }, env) {
+    if (isFullyConfigured) {
+        return `Configured`;
+    }
+    if (isPartiallyConfigured) {
+        return createPartiallyConfiguredStatusMessage(envVariables, env);
+    }
+    if (envVariables !== null) {
+        return createNotConfiguredStatusMessage(envVariables);
     }
-    return colorizeAvailableProviderMessage(providerMessage, llmToolStatus);
+    return `Not configured`;
+    // <- Note: Can not be configured via environment variables
 }
 /**
- * Creates the plain-text provider line before optional colorization.
+ * Creates the partial-configuration sentence including missing variables.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createAvailableProviderMessage(llmToolStatus, index, env) {
-    const { title, packageName, className } = llmToolStatus;
-    const providerStatusMessages = createProviderStatusMessages(llmToolStatus, env);
-    return spaceTrim$1(`
-        ${index + 1}) **${title}** \`${className}\` from \`${packageName}\`
-            ${providerStatusMessages.join('; ')}
-    `);
+function createPartiallyConfiguredStatusMessage(envVariables, env) {
+    return `Partially confugured, missing ${listMissingEnvironmentVariables(envVariables, env).join(' + ')}`;
 }
 /**
- * Creates the install and configuration fragments for one provider line.
+ * Creates the not-configured sentence including the expected environment variables.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createProviderStatusMessages(llmToolStatus, env) {
-    return [createInstallationStatusMessage(llmToolStatus), createConfigurationStatusMessage(llmToolStatus, env)];
+function createNotConfiguredStatusMessage(envVariables) {
+    return `Not configured, to configure set env ${envVariables === null || envVariables === void 0 ? void 0 : envVariables.join(' + ')}`;
+}
+/**
+ * Lists environment variables that are required but currently missing.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function listMissingEnvironmentVariables(envVariables, env) {
+    return (envVariables === null || envVariables === void 0 ? void 0 : envVariables.filter((envVariable) => env[envVariable] === undefined)) || [];
 }
+
 /**
  * Creates the installation-status sentence for one provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createInstallationStatusMessage({ isMetadataAvailable, isInstalled, }) {
-    const installationStatusKey = createInstallationStatusKey(isMetadataAvailable, isInstalled);
+function createRegisteredLlmToolInstallationStatusMessage({ isMetadataAvailable, isInstalled, }) {
+    const installationStatusKey = createRegisteredLlmToolInstallationStatusKey(isMetadataAvailable, isInstalled);
     switch (installationStatusKey) {
         case 'missing-metadata-and-installation':
-            // TODO: [�][�] Maybe do allow to do auto-install if package not registered and not found
             return `Not installed and no metadata, looks like a unexpected behavior`;
         case 'metadata-without-installation':
-            // TODO: [�][�]
             return `Not installed`;
         case 'installation-without-metadata':
             return `No metadata but installed, looks like a unexpected behavior`;
@@ -43334,9 +43988,9 @@ function createInstallationStatusMessage({ isMetadataAvailable, isInstalled, })
 /**
  * Creates a stable installation-state key from metadata and constructor availability.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createInstallationStatusKey(isMetadataAvailable, isInstalled) {
+function createRegisteredLlmToolInstallationStatusKey(isMetadataAvailable, isInstalled) {
     if (!isMetadataAvailable && !isInstalled) {
         return 'missing-metadata-and-installation';
     }
@@ -43351,54 +44005,59 @@ function createInstallationStatusKey(isMetadataAvailable, isInstalled) {
     }
     return 'unknown';
 }
+
 /**
- * Creates the configuration-status sentence for one provider.
+ * Renders all provider lines in the status summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createConfigurationStatusMessage({ envVariables, isFullyConfigured, isPartiallyConfigured }, env) {
-    if (isFullyConfigured) {
-        return `Configured`;
-    }
-    if (isPartiallyConfigured) {
-        return createPartiallyConfiguredStatusMessage(envVariables, env);
-    }
-    if (envVariables !== null) {
-        return createNotConfiguredStatusMessage(envVariables);
-    }
-    return `Not configured`;
-    // <- Note: Can not be configured via environment variables
+function renderAvailableRegisteredLlmTools(llmToolStatuses, env, isRunningInNode) {
+    return llmToolStatuses
+        .map((llmToolStatus, index) => renderAvailableRegisteredLlmTool(llmToolStatus, index, env, isRunningInNode))
+        .join('\n');
 }
 /**
- * Creates the partial-configuration sentence including missing variables.
+ * Renders one provider line in the status summary.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createPartiallyConfiguredStatusMessage(envVariables, env) {
-    return `Partially confugured, missing ${listMissingEnvironmentVariables(envVariables, env).join(' + ')}`;
+function renderAvailableRegisteredLlmTool(llmToolStatus, index, env, isRunningInNode) {
+    const providerMessage = createAvailableRegisteredLlmToolMessage(llmToolStatus, index, env);
+    if (!isRunningInNode) {
+        return providerMessage;
+    }
+    return colorizeAvailableRegisteredLlmToolMessage(providerMessage, llmToolStatus);
 }
 /**
- * Creates the not-configured sentence including the expected environment variables.
+ * Creates the plain-text provider line before optional colorization.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createNotConfiguredStatusMessage(envVariables) {
-    return `Not configured, to configure set env ${envVariables === null || envVariables === void 0 ? void 0 : envVariables.join(' + ')}`;
+function createAvailableRegisteredLlmToolMessage(llmToolStatus, index, env) {
+    const { title, packageName, className } = llmToolStatus;
+    const providerStatusMessages = createRegisteredLlmToolStatusMessages(llmToolStatus, env);
+    return spaceTrim$1(`
+        ${index + 1}) **${title}** \`${className}\` from \`${packageName}\`
+            ${providerStatusMessages.join('; ')}
+    `);
 }
 /**
- * Lists environment variables that are required but currently missing.
+ * Creates the install and configuration fragments for one provider line.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function listMissingEnvironmentVariables(envVariables, env) {
-    return (envVariables === null || envVariables === void 0 ? void 0 : envVariables.filter((envVariable) => env[envVariable] === undefined)) || [];
+function createRegisteredLlmToolStatusMessages(llmToolStatus, env) {
+    return [
+        createRegisteredLlmToolInstallationStatusMessage(llmToolStatus),
+        createRegisteredLlmToolConfigurationStatusMessage(llmToolStatus, env),
+    ];
 }
 /**
  * Applies the same terminal coloring rules as the original summary renderer.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function colorizeAvailableProviderMessage(providerMessage, { isInstalled, isFullyConfigured, isPartiallyConfigured }) {
+function colorizeAvailableRegisteredLlmToolMessage(providerMessage, { isInstalled, isFullyConfigured, isPartiallyConfigured }) {
     if (isInstalled && isFullyConfigured) {
         return colors.green(providerMessage);
     }
@@ -43407,18 +44066,67 @@ function colorizeAvailableProviderMessage(providerMessage, { isInstalled, isFull
     }
     return colors.gray(providerMessage);
 }
+
 /**
- * Creates the `.env` origin sentence used in the summary header.
+ * Renders the list of environment variables used by at least one registered provider.
  *
- * @private internal function of `$registeredLlmToolsMessage`
+ * @private function of `$registeredLlmToolsMessage`
  */
-function createUsedEnvMessage() {
-    return $usedEnvFilename === null
-        ? `Unknown \`.env\` file`
-        : spaceTrim$1(`
-              Used \`.env\` file:
-              ${$usedEnvFilename}
-          `);
+function renderRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses) {
+    return listRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses)
+        .map((envVariableName) => `- \`${envVariableName}\``)
+        .join('\n');
+}
+/**
+ * Lists environment variables that are both present and used by at least one provider.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function listRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses) {
+    return Object.keys(env).filter((envVariableName) => llmToolStatuses.some(({ envVariables }) => envVariables === null || envVariables === void 0 ? void 0 : envVariables.includes(envVariableName)));
+}
+
+/**
+ * Renders the full provider status summary.
+ *
+ * @private function of `$registeredLlmToolsMessage`
+ */
+function renderRegisteredLlmToolsMessage({ env, llmToolStatuses, usedEnvMessage, isRunningInNode, }) {
+    return spaceTrim$1((block) => `
+
+            ${block(usedEnvMessage)}
+
+            Relevant environment variables:
+            ${block(renderRelevantRegisteredLlmToolsEnvironmentVariables(env, llmToolStatuses))}
+
+            Available LLM providers are:
+            ${block(renderAvailableRegisteredLlmTools(llmToolStatuses, env, isRunningInNode))}
+        `);
+}
+
+/**
+ * Pass the `.env` file which was used to configure LLM tools
+ *
+ * Note: `$` is used to indicate that this variable is making side effect
+ *
+ * @private internal log of `$provideLlmToolsConfigurationFromEnv` and `$registeredLlmToolsMessage`
+ */
+function $setUsedEnvFilename(filepath) {
+    USED_ENV_FILENAME.set(filepath);
+}
+/**
+ * Creates a message with all registered LLM tools
+ *
+ * Note: This function is used to create a (error) message when there is no constructor for some LLM provider
+ *
+ * @private internal function of `createLlmToolsFromConfiguration` and `$provideLlmToolsFromEnv`
+ */
+function $registeredLlmToolsMessage() {
+    const registeredLlmToolsMessageContext = createRegisteredLlmToolsMessageContext();
+    if (registeredLlmToolsMessageContext.llmToolStatuses.length === 0) {
+        return renderNoRegisteredLlmToolsMessage(registeredLlmToolsMessageContext.usedEnvMessage);
+    }
+    return renderRegisteredLlmToolsMessage(registeredLlmToolsMessageContext);
 }
 // TODO: [®] DRY Register logic
 // TODO: [🧠][⚛] Maybe pass env as argument