@promptbook/node 0.113.0-0 → 0.113.0-10

package/umd/index.umd.js

@@ -1,8 +1,8 @@
 (function (global, factory) {
-    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('path'), require('fs/promises'), require('colors'), require('child_process'), require('spacetrim'), require('@openai/agents'), require('url'), require('@mozilla/readability'), require('jsdom'), require('crypto-js'), require('crypto-js/enc-hex'), require('showdown'), require('jszip'), require('waitasecond'), require('dotenv'), require('crypto-js/sha256'), require('rxjs'), require('crypto'), require('moment'), require('mime-types'), require('papaparse'), require('bottleneck'), require('openai')) :
-    typeof define === 'function' && define.amd ? define(['exports', 'path', 'fs/promises', 'colors', 'child_process', 'spacetrim', '@openai/agents', 'url', '@mozilla/readability', 'jsdom', 'crypto-js', 'crypto-js/enc-hex', 'showdown', 'jszip', 'waitasecond', 'dotenv', 'crypto-js/sha256', 'rxjs', 'crypto', 'moment', 'mime-types', 'papaparse', 'bottleneck', 'openai'], factory) :
-    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.path, global.promises, global.colors, global.child_process, global._spaceTrim, global.agents, global.url, global.readability, global.jsdom, global.CryptoJS, global.hexEncoder, global.showdown, global.JSZip, global.waitasecond, global.dotenv, global.sha256, global.rxjs, null, global.moment, global.mimeTypes, global.papaparse, global.Bottleneck, global.OpenAI));
-})(this, (function (exports, path, promises, colors, child_process, _spaceTrim, agents, url, readability, jsdom, CryptoJS, hexEncoder, showdown, JSZip, waitasecond, dotenv, sha256, rxjs, crypto, moment, mimeTypes, papaparse, Bottleneck, OpenAI) { 'use strict';
+    typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('path'), require('fs/promises'), require('spacetrim'), require('colors'), require('child_process'), require('@openai/agents'), require('url'), require('@mozilla/readability'), require('jsdom'), require('crypto-js'), require('crypto-js/enc-hex'), require('showdown'), require('jszip'), require('waitasecond'), require('dotenv'), require('crypto-js/sha256'), require('rxjs'), require('crypto'), require('moment'), require('mime-types'), require('papaparse'), require('bottleneck'), require('openai')) :
+    typeof define === 'function' && define.amd ? define(['exports', 'path', 'fs/promises', 'spacetrim', 'colors', 'child_process', '@openai/agents', 'url', '@mozilla/readability', 'jsdom', 'crypto-js', 'crypto-js/enc-hex', 'showdown', 'jszip', 'waitasecond', 'dotenv', 'crypto-js/sha256', 'rxjs', 'crypto', 'moment', 'mime-types', 'papaparse', 'bottleneck', 'openai'], factory) :
+    (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["promptbook-node"] = {}, global.path, global.promises, global._spaceTrim, global.colors, global.child_process, global.agents, global.url, global.readability, global.jsdom, global.CryptoJS, global.hexEncoder, global.showdown, global.JSZip, global.waitasecond, global.dotenv, global.sha256, global.rxjs, null, global.moment, global.mimeTypes, global.papaparse, global.Bottleneck, global.OpenAI));
+})(this, (function (exports, path, promises, _spaceTrim, colors, child_process, agents, url, readability, jsdom, CryptoJS, hexEncoder, showdown, JSZip, waitasecond, dotenv, sha256, rxjs, crypto, moment, mimeTypes, papaparse, Bottleneck, OpenAI) { 'use strict';
 
     function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -24,8 +24,8 @@
         return Object.freeze(n);
     }
 
-    var colors__default = /*#__PURE__*/_interopDefaultLegacy(colors);
     var _spaceTrim__default = /*#__PURE__*/_interopDefaultLegacy(_spaceTrim);
+    var colors__default = /*#__PURE__*/_interopDefaultLegacy(colors);
     var CryptoJS__default = /*#__PURE__*/_interopDefaultLegacy(CryptoJS);
     var hexEncoder__default = /*#__PURE__*/_interopDefaultLegacy(hexEncoder);
     var showdown__default = /*#__PURE__*/_interopDefaultLegacy(showdown);
@@ -51,7 +51,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-0';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-10';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -396,6 +396,34 @@
     // 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.
      */
@@ -408,7 +436,13 @@
         if (normalizedPrompt === '') {
             return normalizedContext;
         }
-        return `${normalizedPrompt}\n\n${normalizedContext}`;
+        return _spaceTrim.spaceTrim((block) => `
+            ${block(normalizedPrompt)}
+
+            ## Context
+        
+            ${block(increaseHeadings(normalizedContext))}
+        `);
     }
 
     /**
@@ -537,6 +571,127 @@
         });
     }
 
+    /**
+     * 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
      *
@@ -696,127 +851,6 @@
     };
     // 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
      *
@@ -2790,6 +2824,31 @@
      * 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.
      */
@@ -3025,15 +3084,211 @@
      * Builds the shell script that runs Claude Code with the prompt and coding context.
      */
     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"${THINKING_LEVEL_ARGUMENT} --output-format json --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
@@ -3109,14 +3364,8 @@
     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) +
@@ -3160,6 +3409,10 @@
         }
     }
 
+    /**
+     * 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.
      */
@@ -3175,21 +3428,102 @@
          * 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, _c;
+        const delayMs = getClaudeCodeSessionLimitDelayMs(sessionLimit);
+        const sessionLabel = formatClaudeCodeSessionIdForDisplay(sessionLimit.sessionId);
+        const resetSummary = formatClaudeCodeSessionLimitForDisplay(sessionLimit);
+        if ((_a = options.shouldPrintLiveOutput) !== null && _a !== void 0 ? _a : true) {
+            console.warn(colors__default["default"].yellow(`[claude-code] Session limit detected for ${sessionLimit.sessionId}. Resurrection #${resurrectionCount} will resume with --resume after ${formatDurationMs(delayMs)}. ${resetSummary}`));
+        }
+        let remainingDelayMs = delayMs;
+        while (remainingDelayMs > 0) {
+            await ((_b = options.waitForPauseCheckpoint) === null || _b === void 0 ? void 0 : _b.call(options, {
+                checkpointLabel: 'the Claude Code session limit reset',
+                phase: 'waiting',
+                statusMessage: `Claude Code session ${sessionLabel} hit its limit; resurrection #${resurrectionCount} resumes in ${formatDurationMs(remainingDelayMs)}`,
+            }));
+            const currentDelayMs = Math.min(CLAUDE_CODE_SESSION_RESURRECTION_POLL_MS, remainingDelayMs);
+            await waitFor$1(currentDelayMs);
+            remainingDelayMs -= currentDelayMs;
+        }
+        await ((_c = options.waitForPauseCheckpoint) === null || _c === void 0 ? void 0 : _c.call(options, {
+            checkpointLabel: 'resurrecting the Claude Code session with --resume',
+            phase: 'running',
+            statusMessage: `Resurrecting Claude Code session ${sessionLabel} with --resume`,
+        }));
+    }
+    /**
+     * Waits for a fixed amount of milliseconds.
+     */
+    async function waitFor$1(delayMs) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+    /**
+     * Formats a Claude Code session id for compact terminal status lines.
+     */
+    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.
@@ -4437,8 +4771,9 @@
         }
         if (agentName === 'claude-code') {
             return createRunnerResolution(options, new ClaudeCodeRunner({
+                model: options.model,
                 thinkingLevel: options.thinkingLevel,
-            }));
+            }), options.model);
         }
         if (agentName === 'opencode') {
             return createRunnerResolution(options, new OpencodeRunner({
@@ -4512,7 +4847,7 @@
         if (options.agentName === 'cline') {
             return { runnerName, modelName: CLINE_MODEL };
         }
-        if (options.agentName === 'opencode') {
+        if (options.agentName === 'opencode' || options.agentName === 'claude-code') {
             return { runnerName, modelName: options.model };
         }
         return { runnerName };
@@ -4589,9 +4924,10 @@
 
                 [Up to 50,000 CZK](?message=We are posting an order up to 50,000 CZK)
                 [Up to 100,000 CZK](?message=We are posting an order up to 100,000 CZK)
-                [Over 100,000 CZK](?message=We are posting an order over 100,000 CZK)
+                [Over 100,000 CZK](?messageDraft=We are posting an order over 100,000 CZK)
                 \`\`\`
 
+                - 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.
 
                 ## This is how you should behave
 
@@ -4599,28 +4935,38 @@
             `);
     }
 
-    /**
-     * Builds a normalized temporary shell script path for prompt runners.
-     */
-    function buildTemporaryPromptScriptPath(options) {
-        const sourceFileName = path.basename(options.sourceFileName);
-        const scriptFileName = `${sourceFileName.replace(/\.[^.]+$/u, '')}${options.suffix || ''}.sh`;
-        return resolvePromptbookTemporaryPath(options.projectPath, options.scriptDirectoryName, scriptFileName);
-    }
-
     /**
      * Temporary subdirectory used for agent-message runner shell scripts.
+     *
+     * @private internal constant of agent-message runtime paths
      */
     const AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME = 'agent-messages';
+    /**
+     * File extension used for temporary prompt-runner shell scripts.
+     *
+     * @private internal constant of agent-message runtime paths
+     */
+    const AGENT_MESSAGE_SCRIPT_EXTENSION = '.sh';
+    /**
+     * Builds the temporary shell script path used by one queued agent-message harness run.
+     *
+     * @param projectPath - Local agent project path containing the message queue.
+     * @param sourceFileName - Queued message filename used to name the temporary shell script.
+     * @returns Temporary shell script path.
+     * @private internal utility of agent-message runners
+     */
+    function buildAgentMessageScriptPathFromFileName(projectPath, sourceFileName) {
+        const sourceFileBasename = path.basename(sourceFileName);
+        const scriptFileName = `${sourceFileBasename.replace(/\.[^.]+$/u, '')}${AGENT_MESSAGE_SCRIPT_EXTENSION}`;
+        return resolvePromptbookTemporaryPath(projectPath, AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME, scriptFileName);
+    }
+    // Note: [💞] Ignore a discrepancy between file name and entity name
+
     /**
      * Builds a temporary script path for one agent message runner invocation.
      */
     function buildAgentMessageScriptPath(projectPath, messageFile) {
-        return buildTemporaryPromptScriptPath({
-            projectPath,
-            scriptDirectoryName: AGENT_MESSAGE_SCRIPT_DIRECTORY_NAME,
-            sourceFileName: messageFile.fileName,
-        });
+        return buildAgentMessageScriptPathFromFileName(projectPath, messageFile.fileName);
     }
 
     var PipelineCollection = [{title:"Prepare Knowledge from Markdown",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book",formfactorName:"GENERIC",parameters:[{name:"knowledgeContent",description:"Markdown document content",isInput:true,isOutput:false},{name:"knowledgePieces",description:"The knowledge JSON object",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}",resultingParameterName:"knowledgePieces",dependentParameterNames:["knowledgeContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge from Markdown\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-from-markdown.book`\n-   INPUT PARAMETER `{knowledgeContent}` Markdown document content\n-   OUTPUT PARAMETER `{knowledgePieces}` The knowledge JSON object\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, extract the important knowledge from the document.\n\n# Rules\n\n-   Make pieces of information concise, clear, and easy to understand\n-   One piece of information should be approximately 1 paragraph\n-   Divide the paragraphs by markdown horizontal lines ---\n-   Omit irrelevant information\n-   Group redundant information\n-   Write just extracted information, nothing else\n\n# The document\n\nTake information from this document:\n\n> {knowledgeContent}\n```\n\n`-> {knowledgePieces}`\n"}],sourceFile:"./books/prepare-knowledge-from-markdown.book"},{title:"Prepare Keywords",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-keywords.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"keywords",description:"Keywords separated by comma",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}",resultingParameterName:"keywords",dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Keywords\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-keywords.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{keywords}` Keywords separated by comma\n\n## Knowledge\n\n<!-- TODO: [🍆] -FORMAT JSON -->\n\n```markdown\nYou are experienced data researcher, detect the important keywords in the document.\n\n# Rules\n\n-   Write just keywords separated by comma\n\n# The document\n\nTake information from this document:\n\n> {knowledgePieceContent}\n```\n\n`-> {keywords}`\n"}],sourceFile:"./books/prepare-knowledge-keywords.book"},{title:"Prepare Knowledge-piece Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-knowledge-title.book",formfactorName:"GENERIC",parameters:[{name:"knowledgePieceContent",description:"The content",isInput:true,isOutput:false},{name:"title",description:"The title of the document",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"knowledge",title:"Knowledge",content:"You are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}",resultingParameterName:"title",expectations:{words:{min:1,max:8}},dependentParameterNames:["knowledgePieceContent"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Knowledge-piece Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-knowledge-title.book`\n-   INPUT PARAMETER `{knowledgePieceContent}` The content\n-   OUTPUT PARAMETER `{title}` The title of the document\n\n## Knowledge\n\n-   EXPECT MIN 1 WORD\n-   EXPECT MAX 8 WORDS\n\n```markdown\nYou are experienced content creator, write best title for the document.\n\n# Rules\n\n-   Write just title, nothing else\n-   Write maximum 5 words for the title\n\n# The document\n\n> {knowledgePieceContent}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-knowledge-title.book"},{title:"Prepare Persona",pipelineUrl:"https://promptbook.studio/promptbook/prepare-persona.book",formfactorName:"GENERIC",parameters:[{name:"availableModels",description:"List of available model names together with their descriptions as JSON",isInput:true,isOutput:false},{name:"personaDescription",description:"Description of the persona",isInput:true,isOutput:false},{name:"modelsRequirements",description:"Specific requirements for the model",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-model-requirements",title:"Make modelRequirements",content:"You are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n```json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n```\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n```json\n{availableModels}\n```\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}",resultingParameterName:"modelsRequirements",format:"JSON",dependentParameterNames:["availableModels","personaDescription"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Persona\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-persona.book`\n-   INPUT PARAMETER `{availableModels}` List of available model names together with their descriptions as JSON\n-   INPUT PARAMETER `{personaDescription}` Description of the persona\n-   OUTPUT PARAMETER `{modelsRequirements}` Specific requirements for the model\n\n## Make modelRequirements\n\n-   FORMAT JSON\n\n```markdown\nYou are an experienced AI engineer, you need to find the best models for virtual assistants:\n\n## Example\n\n\\`\\`\\`json\n[\n  {\n  \"modelName\": \"gpt-4o\",\n  \"systemMessage\": \"You are experienced AI engineer and helpful assistant.\",\n  \"temperature\": 0.7\n  },\n  {\n    \"modelName\": \"claude-3-5-sonnet\",\n    \"systemMessage\": \"You are a friendly and knowledgeable chatbot.\",\n    \"temperature\": 0.5\n  }\n]\n\\`\\`\\`\n\n## Instructions\n\n-   Your output format is JSON array\n-   Sort best-fitting models first\n-   Omit any models that are not suitable\n-   Write just the JSON, no other text should be present\n-   Array contain items with following keys:\n    -   `modelName`: The name of the model to use\n    -   `systemMessage`: The system message to provide context to the model\n    -   `temperature`: The sampling temperature to use\n\n### Key `modelName`\n\nHere are the available models:\n\n\\`\\`\\`json\n{availableModels}\n\\`\\`\\`\n\n### Key `systemMessage`\n\nThe system message is used to communicate instructions or provide context to the model at the beginning of a conversation. It is displayed in a different format compared to user messages, helping the model understand its role in the conversation. The system message typically guides the model's behavior, sets the tone, or specifies desired output from the model. By utilizing the system message effectively, users can steer the model towards generating more accurate and relevant responses.\n\nFor example:\n\n> You are an experienced AI engineer and helpful assistant.\n\n> You are a friendly and knowledgeable chatbot.\n\n### Key `temperature`\n\nThe sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit.\n\nYou can pick a value between 0 and 2. For example:\n\n-   `0.1`: Low temperature, extremely conservative and deterministic\n-   `0.5`: Medium temperature, balanced between conservative and creative\n-   `1.0`: High temperature, creative and bit random\n-   `1.5`: Very high temperature, extremely creative and often chaotic and unpredictable\n-   `2.0`: Maximum temperature, completely random and unpredictable, for some extreme creative use cases\n\n# The assistant\n\nTake this description of the persona:\n\n> {personaDescription}\n```\n\n`-> {modelsRequirements}`\n"}],sourceFile:"./books/prepare-persona.book"},{title:"Prepare Title",pipelineUrl:"https://promptbook.studio/promptbook/prepare-title.book",formfactorName:"GENERIC",parameters:[{name:"book",description:"The book to prepare the title for",isInput:true,isOutput:false},{name:"title",description:"Best title for the book",isInput:false,isOutput:true}],tasks:[{taskType:"PROMPT_TASK",name:"make-title",title:"Make title",content:"Make best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}",resultingParameterName:"title",expectations:{words:{min:1,max:8},lines:{min:1,max:1}},dependentParameterNames:["book"]}],personas:[],preparations:[],knowledgeSources:[],knowledgePieces:[],sources:[{type:"BOOK",path:null,content:"# Prepare Title\n\n-   PIPELINE URL `https://promptbook.studio/promptbook/prepare-title.book`\n-   INPUT PARAMETER `{book}` The book to prepare the title for\n-   OUTPUT PARAMETER `{title}` Best title for the book\n\n## Make title\n\n-   EXPECT MIN 1 Word\n-   EXPECT MAX 8 Words\n-   EXPECT EXACTLY 1 Line\n\n```markdown\nMake best title for given text which describes the workflow:\n\n## Rules\n\n-   Write just title, nothing else\n-   Title should be concise and clear - Write maximum ideally 2 words, maximum 5 words\n-   Title starts with emoticon\n-   Title should not mention the input and output of the workflow but the main purpose of the workflow\n    _For example, not \"✍ Convert Knowledge-piece to title\" but \"✍ Title\"_\n\n## The workflow\n\n> {book}\n```\n\n`-> {title}`\n"}],sourceFile:"./books/prepare-title.book"}];
@@ -5083,6 +5429,95 @@
     // 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.spaceTrim((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.spaceTrim((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
      *
@@ -5195,17 +5630,138 @@
     // 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.spaceTrim((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.spaceTrim((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
@@ -5281,168 +5837,19 @@
     }
     // 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.spaceTrim((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)) {
@@ -5458,7 +5865,7 @@
     /**
      * 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)) {
@@ -5471,48 +5878,31 @@
                 ${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.spaceTrim((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.spaceTrim((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) {
@@ -5529,7 +5919,7 @@
     /**
      * 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)) {
@@ -5548,7 +5938,7 @@
     /**
      * 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)) {
@@ -5567,7 +5957,7 @@
     /**
      * 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));
@@ -5575,23 +5965,46 @@
     /**
      * 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)) {
@@ -5613,7 +6026,7 @@
     /**
      * Validates joker parameters for one task.
      *
-     * @private internal utility of `validatePipeline`
+     * @private internal utility of `validatePipelineTasks`
      */
     function validateTaskJokers(task, pipelineIdentification) {
         if (!hasTaskJokers(task)) {
@@ -5625,7 +6038,7 @@
     /**
      * 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;
@@ -5633,7 +6046,7 @@
     /**
      * 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 */) {
@@ -5648,7 +6061,7 @@
     /**
      * 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) {
@@ -5665,7 +6078,7 @@
     /**
      * 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) {
@@ -5680,7 +6093,7 @@
     /**
      * 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) {
@@ -5695,7 +6108,7 @@
     /**
      * 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) {
@@ -5710,7 +6123,7 @@
     /**
      * 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) {
@@ -5722,123 +6135,62 @@
                 ${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.spaceTrim((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.spaceTrim((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.spaceTrim((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
@@ -14158,7 +14510,7 @@
      * 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
@@ -14173,7 +14525,7 @@
      * 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
@@ -14213,7 +14565,7 @@
 
             ## 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
@@ -14237,7 +14589,7 @@
             \`\`\`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
@@ -17408,452 +17760,13 @@
             .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,
@@ -18092,7 +18005,7 @@
                         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`,
                 });
@@ -18207,7 +18120,7 @@
      *
      * @private helper of `octopus3d3AvatarVisual`
      */
-    const LIGHT_DIRECTION$1 = normalizeVector3({
+    const LIGHT_DIRECTION$2 = normalizeVector3({
         x: 0.34,
         y: -0.62,
         z: 1,
@@ -18514,7 +18427,7 @@
                         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`,
                 });
@@ -18829,7 +18742,7 @@
      *
      * @private helper of `octopus3d4AvatarVisual`
      */
-    const LIGHT_DIRECTION = normalizeVector3({
+    const LIGHT_DIRECTION$1 = normalizeVector3({
         x: 0.32,
         y: -0.66,
         z: 1,
@@ -18900,7 +18813,7 @@
         isAnimated: true,
         supportsPointerTracking: true,
         render({ context, size, palette, createRandom, timeMs, interaction }) {
-            const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots } = getOctopus3d4StableState(createRandom);
+            const { morphologyProfile, animationPhase, leftEyePhaseOffset, rightEyePhaseOffset, tentacleProfiles, skinSpots, } = getOctopus3d4StableState(createRandom);
             const sceneCenterX = size * 0.5;
             const sceneCenterY = size * 0.535;
             const bob = Math.sin(timeMs / 980 + animationPhase) * size * 0.013;
@@ -19175,7 +19088,7 @@
                     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,
@@ -19248,10 +19161,7 @@
             Math.max(0, Math.cos(effectiveLongitude)) * 0.12 +
             lowerBlend * tentacleInfluence.core * (0.12 + tentacleInfluence.depthScale * 0.07) -
             Math.max(0, -Math.cos(effectiveLongitude)) * 0.05;
-        const tentacleTubeRadius = lowerBlend *
-            tentacleInfluence.core *
-            (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) *
-            radiusX;
+        const tentacleTubeRadius = lowerBlend * tentacleInfluence.core * (0.12 + tipBlend * 0.07 + tentacleInfluence.widthScale * 0.028) * radiusX;
         const planarRadiusX = cosineLatitude * radiusX * horizontalScale + tentacleTubeRadius;
         const planarRadiusZ = cosineLatitude * radiusZ * depthScale + tentacleTubeRadius * 0.74;
         const lowerDrop = lowerBlend *
@@ -19263,9 +19173,7 @@
                         (morphologyProfile.tentacles.flowLengthScale - 1) * 0.1));
         const combinedTentacleSway = (primaryTentacleWave + secondaryTentacleWave) * radiusX * (0.06 + tipBlend * 0.06);
         return {
-            x: Math.sin(effectiveLongitude) * planarRadiusX +
-                combinedTentacleSway +
-                tentacleCurl * radiusX * 0.18,
+            x: Math.sin(effectiveLongitude) * planarRadiusX + combinedTentacleSway + tentacleCurl * radiusX * 0.18,
             y: Math.sin(latitude) * radiusY * (1 + upperBlend * 0.14) -
                 upperBlend * radiusY * 0.12 +
                 lowerDrop +
@@ -19579,6 +19487,445 @@
             .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.
@@ -20399,14 +20746,14 @@
     /**
      * 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.
@@ -20426,14 +20773,15 @@
         get documentation() {
             const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
             return _spaceTrim.spaceTrim(`
-            # 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}.
@@ -20448,15 +20796,15 @@
             \`\`\`
 
             \`\`\`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;
         }
@@ -22435,10 +22783,10 @@
      *
      * @private
      */
-    const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
-        '-   If a teammate is relevant to the request, consult that teammate using the matching tool.',
-        '-   Do not ask the user for information that a listed teammate can provide directly.',
-    ];
+    const TEAM_SYSTEM_MESSAGE_GUIDANCE = _spaceTrim.spaceTrim(`
+    -   If a teammate is relevant to the request, consult that teammate using the matching tool.
+    -   Do not ask the user for information that a listed teammate can provide directly.
+`);
     /**
      * Constant for remote agents by Url.
      */
@@ -22620,7 +22968,7 @@
             `);
         });
         return _spaceTrim.spaceTrim((block) => `
-            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES.join('\n'))}
+            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE)}
 
             ${block(teammateSections.join('\n\n'))}
         `);
@@ -29644,6 +29992,7 @@
         new ActionCommitmentDefinition('ACTIONS'),
         new ComponentCommitmentDefinition(),
         new MetaAvatarCommitmentDefinition(),
+        new MetaAvatarCommitmentDefinition('META VISUAL'),
         new MetaImageCommitmentDefinition(),
         new MetaColorCommitmentDefinition(),
         new MetaFontCommitmentDefinition(),
@@ -30995,6 +31344,7 @@
      */
     const META_COMMITMENT_APPLIERS = {
         'META AVATAR': applyMetaAvatarContent,
+        'META VISUAL': applyMetaAvatarContent,
         'META LINK': applyMetaLinkContent,
         'META DOMAIN': applyMetaDomainContent,
         'META IMAGE': applyMetaImageContent,
@@ -31043,7 +31393,7 @@
         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);
@@ -32107,6 +32457,78 @@
             .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()`
      *
@@ -32515,78 +32937,6 @@
         }
     }
 
-    /**
-     * 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.
      */
@@ -43044,18 +43394,6 @@
     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
      *
@@ -43063,61 +43401,53 @@
      */
     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.spaceTrim(`
+                  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 {
@@ -43125,62 +43455,30 @@
             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);
@@ -43194,7 +43492,7 @@
     /**
      * 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 {
@@ -43205,7 +43503,7 @@
     /**
      * 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 {
@@ -43216,7 +43514,7 @@
     /**
      * 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) {
@@ -43227,7 +43525,7 @@
     /**
      * 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) {
@@ -43235,109 +43533,128 @@
         }
         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.spaceTrim((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.spaceTrim((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.spaceTrim((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.spaceTrim(`
-        ${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`;
@@ -43350,9 +43667,9 @@
     /**
      * 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';
         }
@@ -43367,54 +43684,59 @@
         }
         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.spaceTrim(`
+        ${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__default["default"].green(providerMessage);
         }
@@ -43423,18 +43745,67 @@
         }
         return colors__default["default"].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.spaceTrim(`
-              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.spaceTrim((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