@promptbook/node 0.113.0-8 → 0.113.0-9

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-8';
+    const PROMPTBOOK_ENGINE_VERSION = '0.113.0-9';
     /**
      * 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.
      */
@@ -3027,14 +3086,209 @@
     function buildClaudeScript(options) {
         const MODEL_ARGUMENT = options.model ? ` --model ${options.model}` : '';
         const THINKING_LEVEL_ARGUMENT = options.thinkingLevel ? ` --effort ${options.thinkingLevel}` : '';
+        const RESUME_SESSION_ARGUMENT = options.resumeSessionId
+            ? ` --resume ${quoteShellArgument(options.resumeSessionId)}`
+            : '';
         return spaceTrim((block) => `
-            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
+            claude --allowedTools "Bash,Read,Edit,Write"${MODEL_ARGUMENT}${THINKING_LEVEL_ARGUMENT}${RESUME_SESSION_ARGUMENT} --output-format stream-json --verbose --include-partial-messages --print <<'${CLAUDE_PROMPT_DELIMITER}'
 
             ${block(options.prompt)}
 
             ${CLAUDE_PROMPT_DELIMITER}
         `);
     }
+    /**
+     * Quotes one shell argument for the generated Bash script.
+     */
+    function quoteShellArgument(value) {
+        return JSON.stringify(value);
+    }
+
+    /**
+     * Parses all JSON lines from Claude Code output while ignoring shell prefixes and stack traces.
+     */
+    function parseClaudeCodeOutputEvents(output) {
+        return output
+            .split(/\r?\n/u)
+            .map(parseClaudeCodeOutputLine)
+            .filter((event) => event !== undefined);
+    }
+    /**
+     * Finds the final Claude Code result event in a stream-json output blob.
+     */
+    function findClaudeCodeResultEvent(output) {
+        return parseClaudeCodeOutputEvents(output).find((event) => event.type === 'result');
+    }
+    /**
+     * Parses one output line when it contains a JSON object.
+     */
+    function parseClaudeCodeOutputLine(line) {
+        const jsonStartIndex = line.indexOf('{');
+        if (jsonStartIndex === -1) {
+            return undefined;
+        }
+        const possibleJson = line.slice(jsonStartIndex).trim();
+        try {
+            const parsed = JSON.parse(possibleJson);
+            if (isClaudeCodeOutputEvent(parsed)) {
+                return parsed;
+            }
+        }
+        catch (_a) {
+            return undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Checks whether an unknown parsed JSON value has the object shape expected from Claude Code events.
+     */
+    function isClaudeCodeOutputEvent(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+
+    /**
+     * Number of milliseconds added after Claude's reported reset timestamp before retrying.
+     */
+    const CLAUDE_CODE_SESSION_LIMIT_RESET_BUFFER_MS = 30 * 1000;
+    /**
+     * Fallback delay used when Claude reports a session limit without a machine-readable reset timestamp.
+     */
+    const DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS = 10 * 60 * 1000;
+    /**
+     * Extracts a Claude Code session-limit failure from a thrown runner error.
+     */
+    function extractClaudeCodeSessionLimitFromError(error) {
+        return extractClaudeCodeSessionLimitFromOutput(formatUnknownErrorDetails(error));
+    }
+    /**
+     * Extracts a Claude Code session-limit failure from raw stream-json output.
+     */
+    function extractClaudeCodeSessionLimitFromOutput(output) {
+        var _a, _b, _c, _d, _e;
+        const events = parseClaudeCodeOutputEvents(output);
+        const rejectedRateLimitEvent = events.find(isRejectedRateLimitEvent);
+        const sessionLimitResultEvent = events.find(isSessionLimitResultEvent);
+        const sessionLimitTextEvent = events.find(isSessionLimitTextEvent);
+        if (!sessionLimitResultEvent && !sessionLimitTextEvent) {
+            return undefined;
+        }
+        const sessionId = findClaudeCodeSessionId(events);
+        if (!sessionId) {
+            return undefined;
+        }
+        const resetDate = extractResetDate(rejectedRateLimitEvent);
+        const rateLimitType = (_b = (_a = rejectedRateLimitEvent === null || rejectedRateLimitEvent === void 0 ? void 0 : rejectedRateLimitEvent.rate_limit_info) === null || _a === void 0 ? void 0 : _a.rateLimitType) !== null && _b !== void 0 ? _b : (_c = sessionLimitResultEvent === null || sessionLimitResultEvent === void 0 ? void 0 : sessionLimitResultEvent.rate_limit_info) === null || _c === void 0 ? void 0 : _c.rateLimitType;
+        const summary = (_e = (_d = extractSessionLimitSummary(sessionLimitResultEvent)) !== null && _d !== void 0 ? _d : extractSessionLimitSummary(sessionLimitTextEvent)) !== null && _e !== void 0 ? _e : 'Claude Code reported a session limit.';
+        return {
+            sessionId,
+            resetDate,
+            rateLimitType,
+            summary,
+        };
+    }
+    /**
+     * Computes how long to wait before trying to resume the Claude Code session.
+     */
+    function getClaudeCodeSessionLimitDelayMs(sessionLimit, nowMs = Date.now()) {
+        if (!sessionLimit.resetDate) {
+            return DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS;
+        }
+        return Math.max(0, sessionLimit.resetDate.getTime() - nowMs + CLAUDE_CODE_SESSION_LIMIT_RESET_BUFFER_MS);
+    }
+    /**
+     * Builds the follow-up prompt sent into a resumed Claude Code session after its limit resets.
+     */
+    function buildClaudeCodeSessionResurrectionPrompt(originalPrompt, sessionId) {
+        return spaceTrim((block) => `
+            ## Claude Code session resurrection
+
+            You are resuming Claude Code session \`${sessionId}\` after Claude reported a session limit.
+            Continue the same task from the existing repository and session state.
+            Do not discard useful context, completed analysis, or file changes from the resumed session.
+
+            The original prompt is repeated below as reference in case the resumed session needs it.
+
+            ## Original prompt
+
+            ${block(originalPrompt)}
+        `);
+    }
+    /**
+     * Builds a compact one-line label for logs and terminal UI messages.
+     */
+    function formatClaudeCodeSessionLimitForDisplay(sessionLimit) {
+        const resetSuffix = sessionLimit.resetDate
+            ? `, resets at ${sessionLimit.resetDate.toISOString()}`
+            : `, retrying every ${formatDurationMs(DEFAULT_CLAUDE_CODE_SESSION_LIMIT_RETRY_DELAY_MS)}`;
+        const rateLimitSuffix = sessionLimit.rateLimitType ? ` (${sessionLimit.rateLimitType})` : '';
+        return `${sessionLimit.summary}${rateLimitSuffix}${resetSuffix}`;
+    }
+    /**
+     * Returns true when the event is an explicit rejected Claude Code rate-limit event.
+     */
+    function isRejectedRateLimitEvent(event) {
+        var _a;
+        return event.type === 'rate_limit_event' && ((_a = event.rate_limit_info) === null || _a === void 0 ? void 0 : _a.status) === 'rejected';
+    }
+    /**
+     * Returns true when the final result reports the Claude session limit.
+     */
+    function isSessionLimitResultEvent(event) {
+        return (event.type === 'result' &&
+            event.is_error === true &&
+            event.api_error_status === 429 &&
+            isSessionLimitText(event.result));
+    }
+    /**
+     * Returns true when any assistant event reports the Claude session limit in text.
+     */
+    function isSessionLimitTextEvent(event) {
+        if (event.error !== 'rate_limit') {
+            return false;
+        }
+        return isSessionLimitText(extractSessionLimitSummary(event));
+    }
+    /**
+     * Extracts the first session id reported by Claude Code.
+     */
+    function findClaudeCodeSessionId(events) {
+        return events.map((event) => event.session_id).find((sessionId) => Boolean(sessionId));
+    }
+    /**
+     * Extracts Claude's reset timestamp from a rejected rate-limit event.
+     */
+    function extractResetDate(event) {
+        var _a;
+        const resetsAt = (_a = event === null || event === void 0 ? void 0 : event.rate_limit_info) === null || _a === void 0 ? void 0 : _a.resetsAt;
+        if (typeof resetsAt !== 'number' || !Number.isFinite(resetsAt)) {
+            return undefined;
+        }
+        const resetDate = new Date(resetsAt * 1000);
+        if (Number.isNaN(resetDate.getTime())) {
+            return undefined;
+        }
+        return resetDate;
+    }
+    /**
+     * Extracts a human-readable session-limit summary from an event.
+     */
+    function extractSessionLimitSummary(event) {
+        var _a, _b;
+        if (!event) {
+            return undefined;
+        }
+        if (typeof event.result === 'string' && event.result.trim()) {
+            return event.result.trim();
+        }
+        const textContent = (_b = (_a = event.message) === null || _a === void 0 ? void 0 : _a.content) === null || _b === void 0 ? void 0 : _b.map((content) => { var _a; return (content.type === 'text' ? (_a = content.text) === null || _a === void 0 ? void 0 : _a.trim() : undefined); }).find((text) => Boolean(text));
+        return textContent;
+    }
+    /**
+     * Checks whether a text value names the Claude Code session limit.
+     */
+    function isSessionLimitText(text) {
+        return /\bsession\s+limit\b/iu.test(text !== null && text !== void 0 ? text : '');
+    }
 
     /**
      * Represents the uncertain value
@@ -3110,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) +
@@ -3161,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.
      */
@@ -3176,22 +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.
@@ -5087,6 +5419,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
      *
@@ -5199,16 +5620,137 @@
     // 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'))}
+
+
+            `));
     }
 
     /**
@@ -5285,168 +5827,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)) {
@@ -5462,7 +5855,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)) {
@@ -5475,48 +5868,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) {
@@ -5533,7 +5909,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)) {
@@ -5552,7 +5928,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)) {
@@ -5571,7 +5947,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));
@@ -5579,23 +5955,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)) {
@@ -5617,7 +6016,7 @@
     /**
      * Validates joker parameters for one task.
      *
-     * @private internal utility of `validatePipeline`
+     * @private internal utility of `validatePipelineTasks`
      */
     function validateTaskJokers(task, pipelineIdentification) {
         if (!hasTaskJokers(task)) {
@@ -5629,7 +6028,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;
@@ -5637,7 +6036,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 */) {
@@ -5652,7 +6051,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) {
@@ -5669,7 +6068,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) {
@@ -5684,7 +6083,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) {
@@ -5699,7 +6098,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) {
@@ -5714,7 +6113,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) {
@@ -5726,123 +6125,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
@@ -14162,7 +14500,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
@@ -14177,7 +14515,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
@@ -14217,7 +14555,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
@@ -14241,7 +14579,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
@@ -17412,452 +17750,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,
@@ -18096,7 +17995,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`,
                 });
@@ -18211,7 +18110,7 @@
      *
      * @private helper of `octopus3d3AvatarVisual`
      */
-    const LIGHT_DIRECTION$1 = normalizeVector3({
+    const LIGHT_DIRECTION$2 = normalizeVector3({
         x: 0.34,
         y: -0.62,
         z: 1,
@@ -18518,7 +18417,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`,
                 });
@@ -18833,7 +18732,7 @@
      *
      * @private helper of `octopus3d4AvatarVisual`
      */
-    const LIGHT_DIRECTION = normalizeVector3({
+    const LIGHT_DIRECTION$1 = normalizeVector3({
         x: 0.32,
         y: -0.66,
         z: 1,
@@ -19179,7 +19078,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,
@@ -19578,6 +19477,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.
@@ -20398,14 +20736,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.
@@ -20425,14 +20763,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}.
@@ -20447,15 +20786,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;
         }
@@ -29643,6 +29982,7 @@
         new ActionCommitmentDefinition('ACTIONS'),
         new ComponentCommitmentDefinition(),
         new MetaAvatarCommitmentDefinition(),
+        new MetaAvatarCommitmentDefinition('META VISUAL'),
         new MetaImageCommitmentDefinition(),
         new MetaColorCommitmentDefinition(),
         new MetaFontCommitmentDefinition(),
@@ -30994,6 +31334,7 @@
      */
     const META_COMMITMENT_APPLIERS = {
         'META AVATAR': applyMetaAvatarContent,
+        'META VISUAL': applyMetaAvatarContent,
         'META LINK': applyMetaLinkContent,
         'META DOMAIN': applyMetaDomainContent,
         'META IMAGE': applyMetaImageContent,
@@ -31042,7 +31383,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);
@@ -32106,6 +32447,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()`
      *
@@ -32514,78 +32927,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.
      */
@@ -43043,18 +43384,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
      *
@@ -43062,61 +43391,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 {
@@ -43124,62 +43445,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);
@@ -43193,7 +43482,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 {
@@ -43204,7 +43493,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 {
@@ -43215,7 +43504,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) {
@@ -43226,7 +43515,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) {
@@ -43234,109 +43523,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`;
@@ -43349,9 +43657,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';
         }
@@ -43366,54 +43674,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);
         }
@@ -43422,18 +43735,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