@promptbook/ollama 0.112.0-72 → 0.112.0-73

package/esm/index.es.js

@@ -1,7 +1,7 @@
 import { spaceTrim as spaceTrim$1 } from 'spacetrim';
 import { randomBytes } from 'crypto';
-import Bottleneck from 'bottleneck';
 import colors from 'colors';
+import Bottleneck from 'bottleneck';
 import OpenAI from 'openai';
 
 // ⚠️ WARNING: This code has been generated so that any manual changes will be overwritten
@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-72';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-73';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -2814,6 +2814,68 @@ resultContent, rawResponse, duration = ZERO_VALUE) {
 }
 // TODO: [🤝] DRY Maybe some common abstraction between `computeOpenAiUsage` and `computeAnthropicClaudeUsage`
 
+/**
+ * Finds the best hardcoded-model match for one API-listed model identifier.
+ */
+function findHardcodedModelMatch(hardcodedModels, modelId) {
+    return hardcodedModels.find(({ modelName }) => modelName === modelId || modelName.startsWith(modelId) || modelId.startsWith(modelName));
+}
+/**
+ * Creates the fallback model entry used when the API returns an unknown model.
+ */
+function createFallbackModel(modelId) {
+    return {
+        modelVariant: 'CHAT',
+        modelTitle: modelId,
+        modelName: modelId,
+        modelDescription: '',
+    };
+}
+/**
+ * Resolves model lists and default-model lookup for OpenAI-compatible execution tools.
+ *
+ * @private helper of `OpenAiCompatibleExecutionTools`
+ */
+class OpenAiCompatibleModelCatalog {
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Lists available models by merging the live API list with hardcoded metadata when possible.
+     */
+    async listModels() {
+        const client = await this.options.getClient();
+        const rawModelsList = await client.models.list();
+        const hardcodedModels = this.options.getHardcodedModels();
+        return rawModelsList.data
+            .sort((a, b) => (a.created > b.created ? 1 : -1))
+            .map((modelFromApi) => {
+            const modelId = modelFromApi.id;
+            return findHardcodedModelMatch(hardcodedModels, modelId) || createFallbackModel(modelId);
+        });
+    }
+    /**
+     * Resolves one default model by exact or family-prefix name.
+     */
+    getDefaultModel(defaultModelName) {
+        const model = this.options
+            .getHardcodedModels()
+            .find(({ modelName }) => modelName === defaultModelName || modelName.startsWith(defaultModelName));
+        if (model === undefined) {
+            throw new PipelineExecutionError(spaceTrim$1((block) => `
+                            Cannot find model in ${this.options.getTitle()} models with name "${defaultModelName}" which should be used as default.
+
+                            Available models:
+                            ${block(this.options.getHardcodedModels().map(({ modelName }) => `- "${modelName}"`).join('\n'))}
+
+                            Model "${defaultModelName}" is probably not available anymore, not installed, inaccessible or misconfigured.
+
+                        `));
+        }
+        return model;
+    }
+}
+
 /**
  * Simple wrapper `new Date().toISOString()`
  *
@@ -2994,440 +3056,524 @@ function templateParameters(template, parameters) {
 }
 
 /**
- * Marker property stored inside serialized tool-execution envelopes.
+ * Parses an OpenAI error message to identify which parameter is unsupported
  *
- * @private internal tool-execution transport
- */
-const TOOL_EXECUTION_ENVELOPE_MARKER = '__promptbookToolExecutionEnvelope';
-/**
- * Parses one serialized tool-execution envelope when present.
+ * @param errorMessage The error message from OpenAI API
+ * @returns The parameter name that is unsupported, or null if not an unsupported parameter error
  *
- * @private internal tool-execution transport
+ * @private utility of LLM Tools
  */
-function parseToolExecutionEnvelope(rawValue) {
-    if (typeof rawValue !== 'string') {
-        return null;
-    }
-    try {
-        const parsedValue = JSON.parse(rawValue);
-        if (!parsedValue ||
-            typeof parsedValue !== 'object' ||
-            parsedValue[TOOL_EXECUTION_ENVELOPE_MARKER] !== true ||
-            typeof parsedValue.assistantMessage !== 'string') {
-            return null;
-        }
-        return {
-            assistantMessage: parsedValue.assistantMessage,
-            toolResult: parsedValue.toolResult,
-        };
+function parseUnsupportedParameterError(errorMessage) {
+    // Pattern to match "Unsupported value: 'parameter' does not support ..."
+    const unsupportedValueMatch = errorMessage.match(/Unsupported value:\s*'([^']+)'\s*does not support/i);
+    if (unsupportedValueMatch === null || unsupportedValueMatch === void 0 ? void 0 : unsupportedValueMatch[1]) {
+        return unsupportedValueMatch[1];
     }
-    catch (_a) {
-        return null;
+    // Pattern to match "'parameter' of type ... is not supported with this model"
+    const parameterTypeMatch = errorMessage.match(/'([^']+)'\s*of type.*is not supported with this model/i);
+    if (parameterTypeMatch === null || parameterTypeMatch === void 0 ? void 0 : parameterTypeMatch[1]) {
+        return parameterTypeMatch[1];
     }
+    return null;
 }
-// Note: [💞] Ignore a discrepancy between file name and entity name
-
-/**
- * Prompt parameter key used to pass hidden runtime context to tool execution.
- *
- * @private internal runtime wiring for commitment tools
- */
-const TOOL_RUNTIME_CONTEXT_PARAMETER = 'promptbookToolRuntimeContext';
 /**
- * Hidden argument key used to pass runtime context into individual tool calls.
+ * Creates a copy of model requirements with the specified parameter removed
  *
- * @private internal runtime wiring for commitment tools
- */
-const TOOL_RUNTIME_CONTEXT_ARGUMENT = '__promptbookToolRuntimeContext';
-/**
- * Prompt parameter key used to pass a hidden tool-progress listener token into script execution.
+ * @param modelRequirements Original model requirements
+ * @param unsupportedParameter The parameter to remove
+ * @returns New model requirements without the unsupported parameter
  *
- * @private internal runtime wiring for commitment tools
+ * @private utility of LLM Tools
  */
-const TOOL_PROGRESS_TOKEN_PARAMETER = 'promptbookToolProgressToken';
+function removeUnsupportedModelRequirement(modelRequirements, unsupportedParameter) {
+    const newRequirements = { ...modelRequirements };
+    // Map of parameter names that might appear in error messages to ModelRequirements properties
+    const parameterMap = {
+        temperature: 'temperature',
+        max_tokens: 'maxTokens',
+        maxTokens: 'maxTokens',
+        seed: 'seed',
+    };
+    const propertyToRemove = parameterMap[unsupportedParameter];
+    if (propertyToRemove && propertyToRemove in newRequirements) {
+        delete newRequirements[propertyToRemove];
+    }
+    return newRequirements;
+}
 /**
- * Hidden argument key used to pass a tool-progress listener token into individual tool calls.
+ * Checks if an error is an "Unsupported value" error from OpenAI
  *
- * @private internal runtime wiring for commitment tools
- */
-const TOOL_PROGRESS_TOKEN_ARGUMENT = '__promptbookToolProgressToken';
-/**
- * Monotonic counter used for hidden progress-listener tokens.
+ * @param error The error to check
+ * @returns true if this is an unsupported parameter error
  *
- * @private internal runtime wiring for commitment tools
+ * @private utility of LLM Tools
  */
-let toolCallProgressListenerCounter = 0;
+function isUnsupportedParameterError(error) {
+    const errorMessage = error.message.toLowerCase();
+    return (errorMessage.includes('unsupported value:') ||
+        errorMessage.includes('is not supported with this model') ||
+        errorMessage.includes('does not support'));
+}
+
 /**
- * Active tool-progress listeners keyed by hidden execution token.
- *
- * @private internal runtime wiring for commitment tools
+ * Creates one unsupported-parameter retry record.
  */
-const toolCallProgressListeners = new Map();
+function createUnsupportedParameterAttempt(options) {
+    return {
+        modelName: options.modelName,
+        unsupportedParameter: options.unsupportedParameter,
+        errorMessage: options.errorMessage,
+        stripped: options.stripped,
+    };
+}
 /**
- * Registers one in-memory listener that receives progress updates emitted by a running tool.
- *
- * The returned token is passed into script execution as a hidden argument so tool implementations
- * can stream progress without exposing extra parameters to the model.
- *
- * @param listener - Listener notified about tool progress.
- * @returns Hidden token used to route progress updates.
- *
- * @private internal runtime wiring for commitment tools
+ * Formats the retry history exactly as it is reported in thrown errors.
  */
-function registerToolCallProgressListener(listener) {
-    toolCallProgressListenerCounter += 1;
-    const token = `tool-progress:${Date.now()}:${toolCallProgressListenerCounter}`;
-    toolCallProgressListeners.set(token, listener);
-    return token;
+function formatUnsupportedParameterAttemptHistory(attemptStack) {
+    return attemptStack
+        .map((attempt, index) => `  ${index + 1}. Model: ${attempt.modelName}` +
+        (attempt.unsupportedParameter ? `, Stripped: ${attempt.unsupportedParameter}` : '') +
+        `, Error: ${attempt.errorMessage}` +
+        (attempt.stripped ? ' (stripped and retried)' : ''))
+        .join('\n');
 }
 /**
- * Unregisters one in-memory progress listener.
- *
- * @param token - Token previously created by `registerToolCallProgressListener`.
+ * Tracks unsupported-parameter retries for one OpenAI-compatible model call.
  *
- * @private internal runtime wiring for commitment tools
+ * @private helper of `OpenAiCompatibleExecutionTools`
  */
-function unregisterToolCallProgressListener(token) {
-    toolCallProgressListeners.delete(token);
+class OpenAiCompatibleUnsupportedParameterRetrier {
+    constructor(isVerbose) {
+        this.isVerbose = isVerbose;
+        this.attemptStack = [];
+        this.retriedUnsupportedParameters = new Set();
+    }
+    /**
+     * Resolves the next retry attempt after an unsupported-parameter failure or rethrows the final error.
+     */
+    resolveRetryOrThrow(options) {
+        if (!isUnsupportedParameterError(options.error)) {
+            this.throwWithAttemptHistory(options.error);
+        }
+        const unsupportedParameter = parseUnsupportedParameterError(options.error.message);
+        if (!unsupportedParameter) {
+            if (this.isVerbose) {
+                console.warn(colors.bgYellow('Warning'), 'Could not parse unsupported parameter from error:', options.error.message);
+            }
+            throw options.error;
+        }
+        const retryKey = `${options.modelName}-${unsupportedParameter}`;
+        const attempt = createUnsupportedParameterAttempt({
+            modelName: options.modelName,
+            unsupportedParameter,
+            errorMessage: options.error.message,
+            stripped: true,
+        });
+        if (this.retriedUnsupportedParameters.has(retryKey)) {
+            this.attemptStack.push(attempt);
+            throw this.createAttemptHistoryError(options.error.message);
+        }
+        this.retriedUnsupportedParameters.add(retryKey);
+        if (this.isVerbose) {
+            console.warn(colors.bgYellow('Warning'), `Removing unsupported parameter '${unsupportedParameter}' for model '${options.modelName}' and retrying request`);
+        }
+        this.attemptStack.push(attempt);
+        return removeUnsupportedModelRequirement(options.currentModelRequirements, unsupportedParameter);
+    }
+    /**
+     * Rethrows the original error or wraps it with the collected retry history.
+     */
+    throwWithAttemptHistory(error) {
+        if (this.attemptStack.length > 0) {
+            throw this.createAttemptHistoryError(error.message);
+        }
+        throw error;
+    }
+    /**
+     * Creates the retry-history error message shared by all OpenAI-compatible model variants.
+     */
+    createAttemptHistoryError(finalErrorMessage) {
+        return new PipelineExecutionError(spaceTrim$1((block) => `
+                    All attempts failed. Attempt history:
+                    ${block(formatUnsupportedParameterAttemptHistory(this.attemptStack))}
+                    Final error: ${finalErrorMessage}
+                `));
+    }
 }
-// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * This error indicates problems parsing the format value
- *
- * For example, when the format value is not a valid JSON or CSV
- * This is not thrown directly but in extended classes
- *
- * @public exported from `@promptbook/core`
+ * Creates a deep clone of JSON-serializable prompt payloads.
  */
-class AbstractFormatError extends Error {
-    // Note: To allow instanceof do not put here error `name`
-    // public readonly name = 'AbstractFormatError';
-    constructor(message) {
-        super(message);
-        Object.setPrototypeOf(this, AbstractFormatError.prototype);
-    }
+function cloneSerializableValue(value) {
+    return JSON.parse(JSON.stringify(value));
 }
-
 /**
- * This error indicates problem with parsing of CSV
+ * Executes completion, embedding, and image-generation prompts for OpenAI-compatible providers.
  *
- * @public exported from `@promptbook/core`
+ * @private helper of `OpenAiCompatibleExecutionTools`
  */
-class CsvFormatError extends AbstractFormatError {
-    constructor(message) {
-        super(message);
-        this.name = 'CsvFormatError';
-        Object.setPrototypeOf(this, CsvFormatError.prototype);
-    }
-}
-
-/**
- * AuthenticationError is thrown from login function which is dependency of remote server
- *
- * @public exported from `@promptbook/core`
- */
-class AuthenticationError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'AuthenticationError';
-        Object.setPrototypeOf(this, AuthenticationError.prototype);
-    }
-}
-
-/**
- * This error indicates that the pipeline collection cannot be properly loaded
- *
- * @public exported from `@promptbook/core`
- */
-class CollectionError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'CollectionError';
-        Object.setPrototypeOf(this, CollectionError.prototype);
-    }
-}
-
-/**
- * Signals that the requested operation could not be completed because the target already exists.
- *
- * @public exported from `@promptbook/core`
- */
-class ConflictError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ConflictError';
-        Object.setPrototypeOf(this, ConflictError.prototype);
-    }
-}
-
-/**
- * This error indicates error from the database
- *
- * @public exported from `@promptbook/core`
- */
-class DatabaseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'DatabaseError';
-        Object.setPrototypeOf(this, DatabaseError.prototype);
-    }
-}
-// TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
-
-/**
- * This error type indicates that you try to use a feature that is not available in the current environment
- *
- * @public exported from `@promptbook/core`
- */
-class EnvironmentMismatchError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'EnvironmentMismatchError';
-        Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
-    }
-}
-
-/**
- * This error occurs when some expectation is not met in the execution of the pipeline
- *
- * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
- * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
- * Note: This is a kindof subtype of PipelineExecutionError
- *
- * @public exported from `@promptbook/core`
- */
-class ExpectError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ExpectError';
-        Object.setPrototypeOf(this, ExpectError.prototype);
-    }
-}
-
-/**
- * This error indicates that the promptbook can not retrieve knowledge from external sources
- *
- * @public exported from `@promptbook/core`
- */
-class KnowledgeScrapeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'KnowledgeScrapeError';
-        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
-    }
-}
-
-/**
- * This error type indicates that some tools are missing for pipeline execution or preparation
- *
- * @public exported from `@promptbook/core`
- */
-class MissingToolsError extends Error {
-    constructor(message) {
-        super(spaceTrim$1((block) => `
-                    ${block(message)}
-
-                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
-
-                `));
-        this.name = 'MissingToolsError';
-        Object.setPrototypeOf(this, MissingToolsError.prototype);
-    }
-}
-
-/**
- * This error indicates that promptbook operation is not allowed
- *
- * @public exported from `@promptbook/core`
- */
-class NotAllowed extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'NotAllowed';
-        Object.setPrototypeOf(this, NotAllowed.prototype);
+class OpenAiCompatibleNonChatPromptCaller {
+    constructor(options) {
+        this.options = options;
     }
-}
-
-/**
- * This error indicates that promptbook not found in the collection
- *
- * @public exported from `@promptbook/core`
- */
-class NotFoundError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'NotFoundError';
-        Object.setPrototypeOf(this, NotFoundError.prototype);
+    /**
+     * Calls one OpenAI-compatible completion model.
+     */
+    async callCompletionModel(prompt) {
+        const clonedPrompt = cloneSerializableValue(prompt);
+        return this.callCompletionModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
     }
-}
-
-/**
- * This error type indicates that some part of the code is not implemented yet
- *
- * @public exported from `@promptbook/core`
- */
-class NotYetImplementedError extends Error {
-    constructor(message) {
-        super(spaceTrim$1((block) => `
-                    ${block(message)}
-
-                    Note: This feature is not implemented yet but it will be soon.
-
-                    If you want speed up the implementation or just read more, look here:
-                    https://github.com/webgptorg/promptbook
-
-                    Or contact us on pavol@ptbk.io
-
-                `));
-        this.name = 'NotYetImplementedError';
-        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
+    /**
+     * Calls one OpenAI-compatible embedding model.
+     */
+    async callEmbeddingModel(prompt) {
+        const clonedPrompt = cloneSerializableValue(prompt);
+        return this.callEmbeddingModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
     }
-}
-
-/**
- * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
- *
- * @public exported from `@promptbook/core`
- */
-class ParseError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ParseError';
-        Object.setPrototypeOf(this, ParseError.prototype);
+    /**
+     * Calls one OpenAI-compatible image-generation model.
+     */
+    async callImageGenerationModel(prompt) {
+        const clonedPrompt = cloneSerializableValue(prompt);
+        return this.callImageGenerationModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
     }
-}
-// TODO: Maybe split `ParseError` and `ApplyError`
-
-/**
- * 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);
+    /**
+     * Retries completion requests while stripping unsupported model parameters.
+     */
+    async callCompletionModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
+        var _a;
+        const title = this.options.getTitle();
+        if (this.options.isVerbose) {
+            console.info(`🖋 ${title} callCompletionModel call`, { prompt, currentModelRequirements });
+        }
+        const { content, parameters } = prompt;
+        const client = await this.options.getClient();
+        if (currentModelRequirements.modelVariant !== 'COMPLETION') {
+            throw new PipelineExecutionError('Use callCompletionModel only for COMPLETION variant');
+        }
+        const modelName = currentModelRequirements.modelName || this.options.getDefaultCompletionModel().modelName;
+        const modelSettings = {
+            model: modelName,
+            max_tokens: currentModelRequirements.maxTokens,
+            temperature: currentModelRequirements.temperature,
+        };
+        const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+        const rawRequest = {
+            ...modelSettings,
+            model: modelName,
+            prompt: rawPromptContent,
+            user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
+        };
+        const start = $getCurrentDate();
+        if (this.options.isVerbose) {
+            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
+        }
+        try {
+            const turnStart = $getCurrentDate();
+            const rawResponse = await this.options.executeRateLimitedRequest(() => client.completions.create(rawRequest));
+            const turnComplete = $getCurrentDate();
+            if (this.options.isVerbose) {
+                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
+            }
+            if (!rawResponse.choices[0]) {
+                throw new PipelineExecutionError(`No choises from ${title}`);
+            }
+            if (rawResponse.choices.length > 1) {
+                throw new PipelineExecutionError(`More than one choise from ${title}`);
+            }
+            const resultContent = rawResponse.choices[0].text;
+            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
+            const usage = this.options.computeUsage(content || '', resultContent || '', rawResponse, duration);
+            return exportJson({
+                name: 'promptResult',
+                message: `Result of \`OpenAiCompatibleExecutionTools.callCompletionModel\``,
+                order: [],
+                value: {
+                    content: resultContent,
+                    modelName: rawResponse.model || modelName,
+                    timing: {
+                        start,
+                        complete: turnComplete,
+                    },
+                    usage,
+                    rawPromptContent,
+                    rawRequest,
+                    rawResponse,
+                },
+            });
+        }
+        catch (error) {
+            assertsError(error);
+            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
+                error,
+                modelName,
+                currentModelRequirements,
+            });
+            return this.callCompletionModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
+        }
     }
-}
-
-/**
- * This error indicates errors in referencing promptbooks between each other
- *
- * @public exported from `@promptbook/core`
- */
-class PipelineUrlError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PipelineUrlError';
-        Object.setPrototypeOf(this, PipelineUrlError.prototype);
+    /**
+     * Retries embedding requests while stripping unsupported model parameters.
+     */
+    async callEmbeddingModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
+        const title = this.options.getTitle();
+        if (this.options.isVerbose) {
+            console.info(`🖋 ${title} embedding call`, { prompt, currentModelRequirements });
+        }
+        const { content, parameters } = prompt;
+        const client = await this.options.getClient();
+        if (currentModelRequirements.modelVariant !== 'EMBEDDING') {
+            throw new PipelineExecutionError('Use embed only for EMBEDDING variant');
+        }
+        const modelName = currentModelRequirements.modelName || this.options.getDefaultEmbeddingModel().modelName;
+        const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+        const rawRequest = {
+            input: rawPromptContent,
+            model: modelName,
+        };
+        const start = $getCurrentDate();
+        if (this.options.isVerbose) {
+            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
+        }
+        try {
+            const turnStart = $getCurrentDate();
+            const rawResponse = await this.options.executeRateLimitedRequest(() => client.embeddings.create(rawRequest));
+            const turnComplete = $getCurrentDate();
+            if (this.options.isVerbose) {
+                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
+            }
+            if (rawResponse.data.length !== 1) {
+                throw new PipelineExecutionError(`Expected exactly 1 data item in response, got ${rawResponse.data.length}`);
+            }
+            const resultContent = rawResponse.data[0].embedding;
+            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
+            const usage = this.options.computeUsage(content || '', '', rawResponse, duration);
+            return exportJson({
+                name: 'promptResult',
+                message: `Result of \`OpenAiCompatibleExecutionTools.callEmbeddingModel\``,
+                order: [],
+                value: {
+                    content: resultContent,
+                    modelName: rawResponse.model || modelName,
+                    timing: {
+                        start,
+                        complete: turnComplete,
+                    },
+                    usage,
+                    rawPromptContent,
+                    rawRequest,
+                    rawResponse,
+                },
+            });
+        }
+        catch (error) {
+            assertsError(error);
+            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
+                error,
+                modelName,
+                currentModelRequirements,
+            });
+            return this.callEmbeddingModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
+        }
     }
-}
-
-/**
- * Error thrown when a fetch request fails
- *
- * @public exported from `@promptbook/core`
- */
-class PromptbookFetchError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'PromptbookFetchError';
-        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
+    /**
+     * Retries image-generation requests while stripping unsupported model parameters.
+     */
+    async callImageGenerationModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
+        var _a, _b;
+        const title = this.options.getTitle();
+        if (this.options.isVerbose) {
+            console.info(`🎨 ${title} callImageGenerationModel call`, { prompt, currentModelRequirements });
+        }
+        const { content, parameters } = prompt;
+        const client = await this.options.getClient();
+        if (currentModelRequirements.modelVariant !== 'IMAGE_GENERATION') {
+            throw new PipelineExecutionError('Use callImageGenerationModel only for IMAGE_GENERATION variant');
+        }
+        const modelName = currentModelRequirements.modelName || this.options.getDefaultImageGenerationModel().modelName;
+        const modelSettings = {
+            model: modelName,
+            size: currentModelRequirements.size,
+            quality: currentModelRequirements.quality,
+            style: currentModelRequirements.style,
+        };
+        let rawPromptContent = templateParameters(content, { ...parameters, modelName });
+        if ('attachments' in prompt && Array.isArray(prompt.attachments) && prompt.attachments.length > 0) {
+            rawPromptContent += '\n\n' + prompt.attachments.map((attachment) => `Image attachment: ${attachment.url}`).join('\n');
+        }
+        const rawRequest = {
+            ...modelSettings,
+            prompt: rawPromptContent,
+            size: modelSettings.size || '1024x1024',
+            user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
+            response_format: 'url',
+        };
+        const start = $getCurrentDate();
+        if (this.options.isVerbose) {
+            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
+        }
+        try {
+            const turnStart = $getCurrentDate();
+            const rawResponse = await this.options.executeRateLimitedRequest(() => client.images.generate(rawRequest));
+            const turnComplete = $getCurrentDate();
+            if (this.options.isVerbose) {
+                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
+            }
+            if (!rawResponse.data[0]) {
+                throw new PipelineExecutionError(`No choises from ${title}`);
+            }
+            if (rawResponse.data.length > 1) {
+                throw new PipelineExecutionError(`More than one choise from ${title}`);
+            }
+            const resultContent = rawResponse.data[0].url;
+            const modelInfo = this.options.getHardcodedModels().find((model) => model.modelName === modelName);
+            const price = ((_b = modelInfo === null || modelInfo === void 0 ? void 0 : modelInfo.pricing) === null || _b === void 0 ? void 0 : _b.output) ? uncertainNumber(modelInfo.pricing.output) : uncertainNumber();
+            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
+            return exportJson({
+                name: 'promptResult',
+                message: `Result of \`OpenAiCompatibleExecutionTools.callImageGenerationModel\``,
+                order: [],
+                value: {
+                    content: resultContent,
+                    modelName: modelName,
+                    timing: {
+                        start,
+                        complete: turnComplete,
+                    },
+                    usage: {
+                        price,
+                        duration,
+                        input: {
+                            tokensCount: uncertainNumber(0),
+                            ...computeUsageCounts(rawPromptContent),
+                        },
+                        output: {
+                            tokensCount: uncertainNumber(0),
+                            ...computeUsageCounts(''),
+                        },
+                    },
+                    rawPromptContent,
+                    rawRequest,
+                    rawResponse,
+                },
+            });
+        }
+        catch (error) {
+            assertsError(error);
+            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
+                error,
+                modelName,
+                currentModelRequirements,
+            });
+            return this.callImageGenerationModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
+        }
     }
 }
 
 /**
- * Index of all custom errors
- *
- * @public exported from `@promptbook/core`
- */
-const PROMPTBOOK_ERRORS = {
-    AbstractFormatError,
-    CsvFormatError,
-    CollectionError,
-    EnvironmentMismatchError,
-    ExpectError,
-    KnowledgeScrapeError,
-    LimitReachedError,
-    MissingToolsError,
-    NotFoundError,
-    NotYetImplementedError,
-    ParseError,
-    PipelineExecutionError,
-    PipelineLogicError,
-    PipelineUrlError,
-    AuthenticationError,
-    PromptbookFetchError,
-    UnexpectedError,
-    WrappedError,
-    NotAllowed,
-    DatabaseError,
-    ConflictError,
-    // TODO: [🪑]> VersionMismatchError,
-};
-/**
- * Index of all javascript errors
- *
- * @private for internal usage
- */
-const COMMON_JAVASCRIPT_ERRORS = {
-    Error,
-    EvalError,
-    RangeError,
-    ReferenceError,
-    SyntaxError,
-    TypeError,
-    URIError,
-    AggregateError,
-    /*
-  Note: Not widely supported
-  > InternalError,
-  > ModuleError,
-  > HeapError,
-  > WebAssemblyCompileError,
-  > WebAssemblyRuntimeError,
-  */
-};
-/**
- * Index of all errors
- *
- * @private for internal usage
- */
-const ALL_ERRORS = {
-    ...PROMPTBOOK_ERRORS,
-    ...COMMON_JAVASCRIPT_ERRORS,
-};
-// Note: [💞] Ignore a discrepancy between file name and entity name
-
-/**
- * Serializes an error into a [🚉] JSON-serializable object
+ * Manages OpenAI-compatible client creation plus shared retry and rate-limit behavior.
  *
- * @public exported from `@promptbook/utils`
+ * @private helper of `OpenAiCompatibleExecutionTools`
  */
-function serializeError(error) {
-    const { name, message, stack } = error;
-    const { id } = error;
-    if (!Object.keys(ALL_ERRORS).includes(name)) {
-        console.error(spaceTrim$1((block) => `
-
-                    Cannot serialize error with name "${name}"
-
-                    Authors of Promptbook probably forgot to add this error into the list of errors:
-                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
-
-
-                    ${block(stack || message)}
-
-                `));
+class OpenAiCompatibleRequestManager {
+    constructor(options) {
+        this.options = options;
+        this.client = null;
+        this.limiter = new Bottleneck({
+            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+        });
+    }
+    /**
+     * Returns the lazily initialized OpenAI client configured from execution-tool options.
+     */
+    async getClient() {
+        if (this.client === null) {
+            const openAiOptions = { ...this.options };
+            delete openAiOptions.isVerbose;
+            delete openAiOptions.userId;
+            const enhancedOptions = {
+                ...openAiOptions,
+                timeout: API_REQUEST_TIMEOUT,
+                maxRetries: CONNECTION_RETRIES_LIMIT,
+            };
+            this.client = new OpenAI(enhancedOptions);
+        }
+        return this.client;
+    }
+    /**
+     * Schedules one request through the shared limiter and retry policy.
+     */
+    async executeRateLimitedRequest(requestFn) {
+        return this.limiter.schedule(() => this.makeRequestWithNetworkRetry(requestFn)).catch((error) => {
+            assertsError(error);
+            if (this.options.isVerbose) {
+                console.info(colors.bgRed('error'), error);
+            }
+            throw error;
+        });
+    }
+    /**
+     * Retries transient transport errors with exponential backoff.
+     */
+    async makeRequestWithNetworkRetry(requestFn) {
+        let lastError;
+        for (let attempt = 1; attempt <= CONNECTION_RETRIES_LIMIT; attempt++) {
+            try {
+                return await requestFn();
+            }
+            catch (error) {
+                assertsError(error);
+                lastError = error;
+                const isRetryableError = this.isRetryableNetworkError(error);
+                if (!isRetryableError || attempt === CONNECTION_RETRIES_LIMIT) {
+                    if (this.options.isVerbose && this.isRetryableNetworkError(error)) {
+                        console.info(colors.bgRed('Final network error after retries'), `Attempt ${attempt}/${CONNECTION_RETRIES_LIMIT}:`, error);
+                    }
+                    throw error;
+                }
+                const baseDelay = 1000;
+                const backoffDelay = baseDelay * Math.pow(2, attempt - 1);
+                const jitterDelay = Math.random() * 500;
+                const totalDelay = backoffDelay + jitterDelay;
+                if (this.options.isVerbose) {
+                    console.info(colors.bgYellow('Retrying network request'), `Attempt ${attempt}/${CONNECTION_RETRIES_LIMIT}, waiting ${Math.round(totalDelay)}ms:`, error.message);
+                }
+                await new Promise((resolve) => setTimeout(resolve, totalDelay));
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Determines whether the thrown error should be retried as a transient network failure.
+     */
+    isRetryableNetworkError(error) {
+        const errorMessage = error.message.toLowerCase();
+        const errorCode = error.code;
+        const retryableErrors = [
+            'econnreset',
+            'enotfound',
+            'econnrefused',
+            'etimedout',
+            'socket hang up',
+            'network error',
+            'fetch failed',
+            'connection reset',
+            'connection refused',
+            'timeout',
+        ];
+        if (retryableErrors.some((retryableError) => errorMessage.includes(retryableError))) {
+            return true;
+        }
+        if (errorCode && retryableErrors.includes(errorCode.toLowerCase())) {
+            return true;
+        }
+        const errorWithStatus = error;
+        const httpStatus = errorWithStatus.status || errorWithStatus.statusCode;
+        if (httpStatus && [429, 500, 502, 503, 504].includes(httpStatus)) {
+            return true;
+        }
+        return false;
     }
-    return {
-        name: name,
-        message,
-        stack,
-        id, // Include id in the serialized object
-    };
 }
 
 /**
@@ -3485,1261 +3631,1246 @@ function addUsage(...usageItems) {
 }
 
 /**
- * Async version of Array.forEach
- *
- * @param array - Array to iterate over
- * @param options - Options for the function
- * @param callbackfunction - Function to call for each item
- * @deprecated [🪂] Use queues instead
+ * Builds incremental chat progress updates, tool-call snapshots, and the final prompt result.
  *
- * @public exported from `@promptbook/utils`
+ * @private helper of `callOpenAiCompatibleChatModel`
  */
-async function forEachAsync(array, options, callbackfunction) {
-    const { maxParallelCount = Infinity } = options;
-    let index = 0;
-    let runningTasks = [];
-    const tasks = [];
-    for (const item of array) {
-        const currentIndex = index++;
-        const task = callbackfunction(item, currentIndex, array);
-        tasks.push(task);
-        runningTasks.push(task);
-        /* not await */ Promise.resolve(task).then(() => {
-            runningTasks = runningTasks.filter((runningTask) => runningTask !== task);
+class OpenAiCompatibleChatProgressReporter {
+    /**
+     * Creates an empty usage accumulator for multi-turn chat requests.
+     */
+    createEmptyUsage() {
+        return {
+            price: uncertainNumber(0),
+            duration: uncertainNumber(0),
+            input: {
+                tokensCount: uncertainNumber(0),
+                charactersCount: uncertainNumber(0),
+                wordsCount: uncertainNumber(0),
+                sentencesCount: uncertainNumber(0),
+                linesCount: uncertainNumber(0),
+                paragraphsCount: uncertainNumber(0),
+                pagesCount: uncertainNumber(0),
+            },
+            output: {
+                tokensCount: uncertainNumber(0),
+                charactersCount: uncertainNumber(0),
+                wordsCount: uncertainNumber(0),
+                sentencesCount: uncertainNumber(0),
+                linesCount: uncertainNumber(0),
+                paragraphsCount: uncertainNumber(0),
+                pagesCount: uncertainNumber(0),
+            },
+        };
+    }
+    /**
+     * Creates the initial pending snapshot for one chat tool call.
+     */
+    createPendingToolCall(options) {
+        return {
+            name: options.functionName,
+            arguments: options.functionArguments,
+            result: '',
+            rawToolCall: options.toolCall,
+            createdAt: options.calledAt,
+            state: 'PENDING',
+            logs: [
+                this.createToolCallLogEntry({
+                    kind: 'request',
+                    title: 'Request prepared',
+                    message: `Prepared ${options.functionName} request.`,
+                    payload: {
+                        arguments: options.functionArguments,
+                    },
+                }),
+            ],
+        };
+    }
+    /**
+     * Appends one incremental progress update to the currently tracked tool-call snapshot.
+     */
+    applyToolCallProgressUpdate(toolCall, update) {
+        var _a;
+        return {
+            ...toolCall,
+            state: (_a = update.state) !== null && _a !== void 0 ? _a : 'PARTIAL',
+            logs: update.log ? [...(toolCall.logs || []), update.log] : toolCall.logs,
+        };
+    }
+    /**
+     * Finalizes one chat tool-call snapshot after execution ends.
+     */
+    createCompletedToolCall(options) {
+        const hasErrors = options.errors !== undefined && options.errors.length > 0;
+        return {
+            ...options.currentToolCallSnapshot,
+            result: options.toolResult,
+            rawToolCall: options.toolCall,
+            createdAt: options.calledAt,
+            errors: options.errors,
+            state: this.resolveFinalToolCallState({
+                currentState: options.currentToolCallSnapshot.state,
+                errors: options.errors,
+            }),
+            logs: [
+                ...(options.currentToolCallSnapshot.logs || []),
+                this.createToolCallLogEntry({
+                    kind: hasErrors ? 'error' : 'result',
+                    level: hasErrors ? 'error' : 'info',
+                    title: hasErrors ? 'Execution failed' : 'Execution finished',
+                    message: hasErrors
+                        ? `${options.functionName} failed before returning a final result.`
+                        : `${options.functionName} returned a result.`,
+                }),
+            ],
+        };
+    }
+    /**
+     * Emits one chat progress chunk with shared timing, request metadata, and tool-call snapshots.
+     */
+    emitProgress(options) {
+        options.onProgress({
+            content: options.content,
+            modelName: options.modelName,
+            timing: {
+                start: options.start,
+                complete: options.complete || $getCurrentDate(),
+            },
+            usage: options.usage,
+            toolCalls: options.toolCalls,
+            rawPromptContent: options.rawPromptContent,
+            rawRequest: options.rawRequest,
+            rawResponse: options.rawResponse,
         });
-        if (maxParallelCount < runningTasks.length) {
-            await Promise.race(runningTasks);
-        }
     }
-    await Promise.all(tasks);
-}
-
-/**
- * Builds a tool invocation script that injects hidden runtime context into tool args.
- *
- * @private utility of OpenAI tool execution wrappers
- */
-function buildToolInvocationScript(options) {
-    const { functionName, functionArgsExpression } = options;
-    return `
-        const args = ${functionArgsExpression};
-        const runtimeContextRaw =
-            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
-
-        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
-        }
-
-        const toolProgressTokenRaw =
-            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
-                ? undefined
-                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
-
-        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
-            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+    /**
+     * Creates the final chat prompt result after the tool loop has finished.
+     */
+    createChatPromptResult(options) {
+        const resultContent = options.responseMessage.content;
+        if (resultContent === null) {
+            throw new PipelineExecutionError(`No response message from ${options.title}`);
         }
-
-        return await ${functionName}(args);
-    `;
-}
-
-/**
- * Maps Promptbook tools to OpenAI tools.
- *
- * @private
- */
-function mapToolsToOpenAi(tools) {
-    return tools.map((tool) => ({
-        type: 'function',
-        function: {
-            name: tool.name,
-            description: tool.description,
-            parameters: tool.parameters,
-        },
-    }));
-}
-
-/**
- * Parses an OpenAI error message to identify which parameter is unsupported
- *
- * @param errorMessage The error message from OpenAI API
- * @returns The parameter name that is unsupported, or null if not an unsupported parameter error
- *
- * @private utility of LLM Tools
- */
-function parseUnsupportedParameterError(errorMessage) {
-    // Pattern to match "Unsupported value: 'parameter' does not support ..."
-    const unsupportedValueMatch = errorMessage.match(/Unsupported value:\s*'([^']+)'\s*does not support/i);
-    if (unsupportedValueMatch === null || unsupportedValueMatch === void 0 ? void 0 : unsupportedValueMatch[1]) {
-        return unsupportedValueMatch[1];
+        return exportJson({
+            name: 'promptResult',
+            message: `Result of \`OpenAiCompatibleExecutionTools.callChatModel\``,
+            order: [],
+            value: {
+                content: resultContent,
+                modelName: options.rawResponse.model || options.modelName,
+                timing: {
+                    start: options.start,
+                    complete: options.complete,
+                },
+                usage: options.usage,
+                toolCalls: options.toolCalls,
+                rawPromptContent: options.rawPromptContent,
+                rawRequest: options.rawRequest,
+                rawResponse: options.rawResponse,
+            },
+        });
     }
-    // Pattern to match "'parameter' of type ... is not supported with this model"
-    const parameterTypeMatch = errorMessage.match(/'([^']+)'\s*of type.*is not supported with this model/i);
-    if (parameterTypeMatch === null || parameterTypeMatch === void 0 ? void 0 : parameterTypeMatch[1]) {
-        return parameterTypeMatch[1];
+    /**
+     * Creates one structured log entry for streamed tool-call updates.
+     */
+    createToolCallLogEntry(options) {
+        return {
+            createdAt: $getCurrentDate(),
+            kind: options.kind,
+            level: options.level,
+            title: options.title,
+            message: options.message,
+            payload: options.payload,
+        };
     }
-    return null;
-}
-/**
- * Creates a copy of model requirements with the specified parameter removed
- *
- * @param modelRequirements Original model requirements
- * @param unsupportedParameter The parameter to remove
- * @returns New model requirements without the unsupported parameter
- *
- * @private utility of LLM Tools
- */
-function removeUnsupportedModelRequirement(modelRequirements, unsupportedParameter) {
-    const newRequirements = { ...modelRequirements };
-    // Map of parameter names that might appear in error messages to ModelRequirements properties
-    const parameterMap = {
-        temperature: 'temperature',
-        max_tokens: 'maxTokens',
-        maxTokens: 'maxTokens',
-        seed: 'seed',
-    };
-    const propertyToRemove = parameterMap[unsupportedParameter];
-    if (propertyToRemove && propertyToRemove in newRequirements) {
-        delete newRequirements[propertyToRemove];
+    /**
+     * Resolves the final lifecycle state for one tool call after execution ends.
+     */
+    resolveFinalToolCallState(options) {
+        if (options.errors && options.errors.length > 0) {
+            return 'ERROR';
+        }
+        if (options.currentState === 'ERROR') {
+            return 'ERROR';
+        }
+        return 'COMPLETE';
     }
-    return newRequirements;
 }
+
 /**
- * Checks if an error is an "Unsupported value" error from OpenAI
- *
- * @param error The error to check
- * @returns true if this is an unsupported parameter error
+ * Maps Promptbook tools to OpenAI tools.
  *
- * @private utility of LLM Tools
+ * @private
  */
-function isUnsupportedParameterError(error) {
-    const errorMessage = error.message.toLowerCase();
-    return (errorMessage.includes('unsupported value:') ||
-        errorMessage.includes('is not supported with this model') ||
-        errorMessage.includes('does not support'));
+function mapToolsToOpenAi(tools) {
+    return tools.map((tool) => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    }));
 }
 
 /**
- * Creates one unsupported-parameter retry record.
- */
-function createUnsupportedParameterAttempt(options) {
-    return {
-        modelName: options.modelName,
-        unsupportedParameter: options.unsupportedParameter,
-        errorMessage: options.errorMessage,
-        stripped: options.stripped,
-    };
-}
-/**
- * Formats the retry history exactly as it is reported in thrown errors.
- */
-function formatUnsupportedParameterAttemptHistory(attemptStack) {
-    return attemptStack
-        .map((attempt, index) => `  ${index + 1}. Model: ${attempt.modelName}` +
-        (attempt.unsupportedParameter ? `, Stripped: ${attempt.unsupportedParameter}` : '') +
-        `, Error: ${attempt.errorMessage}` +
-        (attempt.stripped ? ' (stripped and retried)' : ''))
-        .join('\n');
-}
-/**
- * Tracks unsupported-parameter retries for one OpenAI-compatible model call.
+ * Builds cloned prompt payloads, OpenAI messages, and raw chat requests.
  *
- * @private helper of `OpenAiCompatibleExecutionTools`
+ * @private helper of `callOpenAiCompatibleChatModel`
  */
-class OpenAiCompatibleUnsupportedParameterRetrier {
-    constructor(isVerbose) {
-        this.isVerbose = isVerbose;
-        this.attemptStack = [];
-        this.retriedUnsupportedParameters = new Set();
-    }
+class OpenAiCompatibleChatPromptBuilder {
     /**
-     * Resolves the next retry attempt after an unsupported-parameter failure or rethrows the final error.
+     * Creates a deep copy of the prompt while keeping attached files intact when structured clone is not available.
      */
-    resolveRetryOrThrow(options) {
-        if (!isUnsupportedParameterError(options.error)) {
-            this.throwWithAttemptHistory(options.error);
+    clonePromptPreservingFiles(prompt) {
+        const structuredCloneFn = this.getStructuredCloneFunction();
+        if (typeof structuredCloneFn === 'function') {
+            return structuredCloneFn(prompt);
         }
-        const unsupportedParameter = parseUnsupportedParameterError(options.error.message);
-        if (!unsupportedParameter) {
-            if (this.isVerbose) {
-                console.warn(colors.bgYellow('Warning'), 'Could not parse unsupported parameter from error:', options.error.message);
-            }
-            throw options.error;
+        const clonedPrompt = JSON.parse(JSON.stringify(prompt));
+        if (this.hasChatPromptFiles(prompt)) {
+            clonedPrompt.files = prompt.files;
         }
-        const retryKey = `${options.modelName}-${unsupportedParameter}`;
-        const attempt = createUnsupportedParameterAttempt({
-            modelName: options.modelName,
-            unsupportedParameter,
-            errorMessage: options.error.message,
-            stripped: true,
-        });
-        if (this.retriedUnsupportedParameters.has(retryKey)) {
-            this.attemptStack.push(attempt);
-            throw this.createAttemptHistoryError(options.error.message);
+        return clonedPrompt;
+    }
+    /**
+     * Resolves OpenAI chat creation settings from model requirements and prompt format.
+     */
+    createModelSettings(options) {
+        const modelSettings = {
+            model: options.modelName,
+            max_tokens: options.currentModelRequirements.maxTokens,
+            temperature: options.currentModelRequirements.temperature,
+        };
+        if (options.currentModelRequirements.responseFormat !== undefined) {
+            modelSettings.response_format = options.currentModelRequirements.responseFormat;
         }
-        this.retriedUnsupportedParameters.add(retryKey);
-        if (this.isVerbose) {
-            console.warn(colors.bgYellow('Warning'), `Removing unsupported parameter '${unsupportedParameter}' for model '${options.modelName}' and retrying request`);
+        else if (options.format === 'JSON') {
+            modelSettings.response_format = {
+                type: 'json_object',
+            };
         }
-        this.attemptStack.push(attempt);
-        return removeUnsupportedModelRequirement(options.currentModelRequirements, unsupportedParameter);
+        return modelSettings;
     }
     /**
-     * Rethrows the original error or wraps it with the collected retry history.
+     * Creates the full OpenAI chat message list, including system, thread, and user content.
      */
-    throwWithAttemptHistory(error) {
-        if (this.attemptStack.length > 0) {
-            throw this.createAttemptHistoryError(error.message);
+    async createMessages(options) {
+        return [
+            ...(options.currentModelRequirements.systemMessage === undefined
+                ? []
+                : [
+                    {
+                        role: 'system',
+                        content: options.currentModelRequirements.systemMessage,
+                    },
+                ]),
+            ...this.createThreadMessages(options.prompt),
+            await this.createPromptUserMessage({
+                prompt: options.prompt,
+                rawPromptContent: options.rawPromptContent,
+            }),
+        ];
+    }
+    /**
+     * Creates one raw OpenAI chat request from the current conversation state.
+     */
+    createRawRequest(options) {
+        var _a;
+        return {
+            ...options.modelSettings,
+            messages: options.messages,
+            user: (_a = options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
+            tools: options.tools === undefined ? undefined : mapToolsToOpenAi(options.tools),
+        };
+    }
+    /**
+     * Provides access to the structured clone implementation when available.
+     */
+    getStructuredCloneFunction() {
+        return globalThis.structuredClone;
+    }
+    /**
+     * Checks whether the prompt is a chat prompt that carries file attachments.
+     */
+    hasChatPromptFiles(prompt) {
+        return 'files' in prompt && Array.isArray(prompt.files);
+    }
+    /**
+     * Converts the existing prompt thread into OpenAI chat messages.
+     */
+    createThreadMessages(prompt) {
+        if (!('thread' in prompt) || !Array.isArray(prompt.thread)) {
+            return [];
         }
-        throw error;
+        return prompt.thread.map((message) => ({
+            role: message.sender === 'assistant' ? 'assistant' : 'user',
+            content: message.content,
+        }));
     }
     /**
-     * Creates the retry-history error message shared by all OpenAI-compatible model variants.
+     * Builds the final user message, including inline image attachments when present.
      */
-    createAttemptHistoryError(finalErrorMessage) {
-        return new PipelineExecutionError(spaceTrim$1((block) => `
-                    All attempts failed. Attempt history:
-                    ${block(formatUnsupportedParameterAttemptHistory(this.attemptStack))}
-                    Final error: ${finalErrorMessage}
-                `));
+    async createPromptUserMessage(options) {
+        if (!('files' in options.prompt) || !Array.isArray(options.prompt.files) || options.prompt.files.length === 0) {
+            return {
+                role: 'user',
+                content: options.rawPromptContent,
+            };
+        }
+        const filesContent = await Promise.all(options.prompt.files.map(async (file) => {
+            const arrayBuffer = await file.arrayBuffer();
+            const base64 = Buffer.from(arrayBuffer).toString('base64');
+            return {
+                type: 'image_url',
+                image_url: {
+                    url: `data:${file.type};base64,${base64}`,
+                },
+            };
+        }));
+        return {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: options.rawPromptContent,
+                },
+                ...filesContent,
+            ],
+        };
+    }
+}
+
+/**
+ * Marker property stored inside serialized tool-execution envelopes.
+ *
+ * @private internal tool-execution transport
+ */
+const TOOL_EXECUTION_ENVELOPE_MARKER = '__promptbookToolExecutionEnvelope';
+/**
+ * Parses one serialized tool-execution envelope when present.
+ *
+ * @private internal tool-execution transport
+ */
+function parseToolExecutionEnvelope(rawValue) {
+    if (typeof rawValue !== 'string') {
+        return null;
+    }
+    try {
+        const parsedValue = JSON.parse(rawValue);
+        if (!parsedValue ||
+            typeof parsedValue !== 'object' ||
+            parsedValue[TOOL_EXECUTION_ENVELOPE_MARKER] !== true ||
+            typeof parsedValue.assistantMessage !== 'string') {
+            return null;
+        }
+        return {
+            assistantMessage: parsedValue.assistantMessage,
+            toolResult: parsedValue.toolResult,
+        };
+    }
+    catch (_a) {
+        return null;
     }
 }
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * Provides access to the structured clone implementation when available.
+ * Prompt parameter key used to pass hidden runtime context to tool execution.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+const TOOL_RUNTIME_CONTEXT_PARAMETER = 'promptbookToolRuntimeContext';
+/**
+ * Hidden argument key used to pass runtime context into individual tool calls.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+const TOOL_RUNTIME_CONTEXT_ARGUMENT = '__promptbookToolRuntimeContext';
+/**
+ * Prompt parameter key used to pass a hidden tool-progress listener token into script execution.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+const TOOL_PROGRESS_TOKEN_PARAMETER = 'promptbookToolProgressToken';
+/**
+ * Hidden argument key used to pass a tool-progress listener token into individual tool calls.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+const TOOL_PROGRESS_TOKEN_ARGUMENT = '__promptbookToolProgressToken';
+/**
+ * Monotonic counter used for hidden progress-listener tokens.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+let toolCallProgressListenerCounter = 0;
+/**
+ * Active tool-progress listeners keyed by hidden execution token.
+ *
+ * @private internal runtime wiring for commitment tools
+ */
+const toolCallProgressListeners = new Map();
+/**
+ * Registers one in-memory listener that receives progress updates emitted by a running tool.
+ *
+ * The returned token is passed into script execution as a hidden argument so tool implementations
+ * can stream progress without exposing extra parameters to the model.
+ *
+ * @param listener - Listener notified about tool progress.
+ * @returns Hidden token used to route progress updates.
+ *
+ * @private internal runtime wiring for commitment tools
  */
-function getStructuredCloneFunction() {
-    return globalThis.structuredClone;
+function registerToolCallProgressListener(listener) {
+    toolCallProgressListenerCounter += 1;
+    const token = `tool-progress:${Date.now()}:${toolCallProgressListenerCounter}`;
+    toolCallProgressListeners.set(token, listener);
+    return token;
 }
 /**
- * Checks whether the prompt is a chat prompt that carries file attachments.
+ * Unregisters one in-memory progress listener.
+ *
+ * @param token - Token previously created by `registerToolCallProgressListener`.
+ *
+ * @private internal runtime wiring for commitment tools
  */
-function hasChatPromptFiles(prompt) {
-    return 'files' in prompt && Array.isArray(prompt.files);
+function unregisterToolCallProgressListener(token) {
+    toolCallProgressListeners.delete(token);
 }
+// Note: [💞] Ignore a discrepancy between file name and entity name
+
 /**
- * Creates a deep copy of the prompt while keeping attached files intact when structured clone is not available.
+ * This error indicates problems parsing the format value
+ *
+ * For example, when the format value is not a valid JSON or CSV
+ * This is not thrown directly but in extended classes
+ *
+ * @public exported from `@promptbook/core`
  */
-function clonePromptPreservingFiles(prompt) {
-    const structuredCloneFn = getStructuredCloneFunction();
-    if (typeof structuredCloneFn === 'function') {
-        return structuredCloneFn(prompt);
-    }
-    const clonedPrompt = JSON.parse(JSON.stringify(prompt));
-    if (hasChatPromptFiles(prompt)) {
-        clonedPrompt.files = prompt.files;
+class AbstractFormatError extends Error {
+    // Note: To allow instanceof do not put here error `name`
+    // public readonly name = 'AbstractFormatError';
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, AbstractFormatError.prototype);
     }
-    return clonedPrompt;
 }
+
 /**
- * Creates one structured log entry for streamed tool-call updates.
+ * This error indicates problem with parsing of CSV
+ *
+ * @public exported from `@promptbook/core`
  */
-function createToolCallLogEntry(options) {
-    return {
-        createdAt: $getCurrentDate(),
-        kind: options.kind,
-        level: options.level,
-        title: options.title,
-        message: options.message,
-        payload: options.payload,
-    };
+class CsvFormatError extends AbstractFormatError {
+    constructor(message) {
+        super(message);
+        this.name = 'CsvFormatError';
+        Object.setPrototypeOf(this, CsvFormatError.prototype);
+    }
 }
+
 /**
- * Appends one incremental progress update to the currently tracked tool-call snapshot.
- */
-function applyToolCallProgressUpdate(toolCall, update) {
-    var _a;
-    return {
-        ...toolCall,
-        state: (_a = update.state) !== null && _a !== void 0 ? _a : 'PARTIAL',
-        logs: update.log ? [...(toolCall.logs || []), update.log] : toolCall.logs,
-    };
+ * AuthenticationError is thrown from login function which is dependency of remote server
+ *
+ * @public exported from `@promptbook/core`
+ */
+class AuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthenticationError';
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
 }
+
 /**
- * Resolves the final lifecycle state for one tool call after execution ends.
+ * This error indicates that the pipeline collection cannot be properly loaded
+ *
+ * @public exported from `@promptbook/core`
  */
-function resolveFinalToolCallState(options) {
-    if (options.errors && options.errors.length > 0) {
-        return 'ERROR';
-    }
-    if (options.currentState === 'ERROR') {
-        return 'ERROR';
+class CollectionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CollectionError';
+        Object.setPrototypeOf(this, CollectionError.prototype);
     }
-    return 'COMPLETE';
 }
+
 /**
- * Creates an empty usage accumulator for multi-turn chat requests.
+ * Signals that the requested operation could not be completed because the target already exists.
+ *
+ * @public exported from `@promptbook/core`
  */
-function createEmptyUsage() {
-    return {
-        price: uncertainNumber(0),
-        duration: uncertainNumber(0),
-        input: {
-            tokensCount: uncertainNumber(0),
-            charactersCount: uncertainNumber(0),
-            wordsCount: uncertainNumber(0),
-            sentencesCount: uncertainNumber(0),
-            linesCount: uncertainNumber(0),
-            paragraphsCount: uncertainNumber(0),
-            pagesCount: uncertainNumber(0),
-        },
-        output: {
-            tokensCount: uncertainNumber(0),
-            charactersCount: uncertainNumber(0),
-            wordsCount: uncertainNumber(0),
-            sentencesCount: uncertainNumber(0),
-            linesCount: uncertainNumber(0),
-            paragraphsCount: uncertainNumber(0),
-            pagesCount: uncertainNumber(0),
-        },
-    };
+class ConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConflictError';
+        Object.setPrototypeOf(this, ConflictError.prototype);
+    }
 }
+
 /**
- * Calls the OpenAI-compatible chat model flow, including tool execution and unsupported-parameter retries.
+ * This error indicates error from the database
  *
- * @private function of `OpenAiCompatibleExecutionTools`
+ * @public exported from `@promptbook/core`
  */
-async function callOpenAiCompatibleChatModel(options) {
-    const clonedPrompt = clonePromptPreservingFiles(options.prompt);
-    const unsupportedParameterRetrier = new OpenAiCompatibleUnsupportedParameterRetrier(options.executionToolsOptions.isVerbose);
-    return callChatModelWithRetry(options, clonedPrompt, clonedPrompt.modelRequirements, unsupportedParameterRetrier);
+class DatabaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DatabaseError';
+        Object.setPrototypeOf(this, DatabaseError.prototype);
+    }
 }
+// TODO: [🐱‍🚀] Explain that NotFoundError ([🐱‍🚀] and other specific errors) has priority over DatabaseError in some contexts
+
 /**
- * Retries the chat flow when OpenAI-compatible providers reject unsupported parameters.
+ * This error type indicates that you try to use a feature that is not available in the current environment
+ *
+ * @public exported from `@promptbook/core`
  */
-async function callChatModelWithRetry(options, prompt, currentModelRequirements, unsupportedParameterRetrier) {
-    if (options.executionToolsOptions.isVerbose) {
-        console.info(`💬 ${options.title} callChatModel call`, { prompt, currentModelRequirements });
-    }
-    const { content, parameters, format } = prompt;
-    if (currentModelRequirements.modelVariant !== 'CHAT') {
-        throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
-    }
-    const modelName = currentModelRequirements.modelName || options.getDefaultChatModel().modelName;
-    const rawPromptContent = templateParameters(content, { ...parameters, modelName });
-    const modelSettings = createChatModelSettings({
-        currentModelRequirements,
-        format,
-        modelName,
-    });
-    const messages = await createChatMessages({
-        prompt,
-        currentModelRequirements,
-        rawPromptContent,
-    });
-    const client = await options.getClient();
-    let totalUsage = createEmptyUsage();
-    const toolCalls = [];
-    const start = $getCurrentDate();
-    const tools = 'tools' in prompt && Array.isArray(prompt.tools) ? prompt.tools : currentModelRequirements.tools;
-    let isToolCallingLoopActive = true;
-    while (isToolCallingLoopActive) {
-        const rawRequest = createChatRawRequest(options, {
-            modelSettings,
-            messages,
-            tools,
-        });
-        try {
-            const turnResult = await executeChatTurn(options, {
-                client,
-                rawRequest,
-                promptContent: content || '',
-            });
-            messages.push(turnResult.responseMessage);
-            totalUsage = addUsage(totalUsage, turnResult.usage);
-            if (turnResult.responseMessage.tool_calls && turnResult.responseMessage.tool_calls.length > 0) {
-                await handleChatToolCalls(options, {
-                    prompt,
-                    start,
-                    turnComplete: turnResult.turnComplete,
-                    rawPromptContent,
-                    responseMessage: turnResult.responseMessage,
-                    rawRequest,
-                    rawResponse: turnResult.rawResponse,
-                    modelName,
-                    usage: totalUsage,
-                    toolCalls,
-                    messages,
-                    onProgress: options.onProgress,
-                });
-                continue;
-            }
-            isToolCallingLoopActive = false;
-            return createChatPromptResult(options, {
-                responseMessage: turnResult.responseMessage,
-                rawPromptContent,
-                rawRequest,
-                rawResponse: turnResult.rawResponse,
-                modelName,
-                start,
-                complete: $getCurrentDate(),
-                usage: totalUsage,
-                toolCalls,
-            });
-        }
-        catch (error) {
-            isToolCallingLoopActive = false;
-            assertsError(error);
-            return callChatModelWithRetry(options, prompt, unsupportedParameterRetrier.resolveRetryOrThrow({
-                error,
-                modelName,
-                currentModelRequirements,
-            }), unsupportedParameterRetrier);
-        }
+class EnvironmentMismatchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvironmentMismatchError';
+        Object.setPrototypeOf(this, EnvironmentMismatchError.prototype);
     }
-    throw new PipelineExecutionError(`Tool calling loop did not return a result from ${options.title}`);
 }
+
 /**
- * Resolves OpenAI chat creation settings from model requirements and prompt format.
+ * This error occurs when some expectation is not met in the execution of the pipeline
+ *
+ * Note: Do not throw this error, its reserved for `checkExpectations` and `createPipelineExecutor` and public ONLY to be serializable through remote server
+ * Note: Always thrown in `checkExpectations` and catched in `createPipelineExecutor` and rethrown as `PipelineExecutionError`
+ * Note: This is a kindof subtype of PipelineExecutionError
+ *
+ * @public exported from `@promptbook/core`
  */
-function createChatModelSettings(options) {
-    const modelSettings = {
-        model: options.modelName,
-        max_tokens: options.currentModelRequirements.maxTokens,
-        temperature: options.currentModelRequirements.temperature,
-    };
-    if (options.currentModelRequirements.responseFormat !== undefined) {
-        modelSettings.response_format = options.currentModelRequirements.responseFormat;
-    }
-    else if (options.format === 'JSON') {
-        modelSettings.response_format = {
-            type: 'json_object',
-        };
+class ExpectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ExpectError';
+        Object.setPrototypeOf(this, ExpectError.prototype);
     }
-    return modelSettings;
 }
+
 /**
- * Creates the full OpenAI chat message list, including system, thread, and user content.
+ * This error indicates that the promptbook can not retrieve knowledge from external sources
+ *
+ * @public exported from `@promptbook/core`
  */
-async function createChatMessages(options) {
-    return [
-        ...(options.currentModelRequirements.systemMessage === undefined
-            ? []
-            : [
-                {
-                    role: 'system',
-                    content: options.currentModelRequirements.systemMessage,
-                },
-            ]),
-        ...createChatThreadMessages(options.prompt),
-        await createChatPromptUserMessage({
-            prompt: options.prompt,
-            rawPromptContent: options.rawPromptContent,
-        }),
-    ];
+class KnowledgeScrapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KnowledgeScrapeError';
+        Object.setPrototypeOf(this, KnowledgeScrapeError.prototype);
+    }
 }
+
 /**
- * Converts the existing prompt thread into OpenAI chat messages.
+ * This error type indicates that some tools are missing for pipeline execution or preparation
+ *
+ * @public exported from `@promptbook/core`
  */
-function createChatThreadMessages(prompt) {
-    if (!('thread' in prompt) || !Array.isArray(prompt.thread)) {
-        return [];
+class MissingToolsError extends Error {
+    constructor(message) {
+        super(spaceTrim$1((block) => `
+                    ${block(message)}
+
+                    Note: You have probably forgot to provide some tools for pipeline execution or preparation
+
+                `));
+        this.name = 'MissingToolsError';
+        Object.setPrototypeOf(this, MissingToolsError.prototype);
     }
-    return prompt.thread.map((message) => ({
-        role: message.sender === 'assistant' ? 'assistant' : 'user',
-        content: message.content,
-    }));
 }
+
 /**
- * Builds the final user message, including inline image attachments when present.
+ * This error indicates that promptbook operation is not allowed
+ *
+ * @public exported from `@promptbook/core`
  */
-async function createChatPromptUserMessage(options) {
-    if (!('files' in options.prompt) || !Array.isArray(options.prompt.files) || options.prompt.files.length === 0) {
-        return {
-            role: 'user',
-            content: options.rawPromptContent,
-        };
+class NotAllowed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotAllowed';
+        Object.setPrototypeOf(this, NotAllowed.prototype);
     }
-    const filesContent = await Promise.all(options.prompt.files.map(async (file) => {
-        const arrayBuffer = await file.arrayBuffer();
-        const base64 = Buffer.from(arrayBuffer).toString('base64');
-        return {
-            type: 'image_url',
-            image_url: {
-                url: `data:${file.type};base64,${base64}`,
-            },
-        };
-    }));
-    return {
-        role: 'user',
-        content: [
-            {
-                type: 'text',
-                text: options.rawPromptContent,
-            },
-            ...filesContent,
-        ],
-    };
 }
+
 /**
- * Creates one raw OpenAI chat request from the current conversation state.
+ * This error indicates that promptbook not found in the collection
+ *
+ * @public exported from `@promptbook/core`
  */
-function createChatRawRequest(openAiOptions, options) {
-    var _a;
-    return {
-        ...options.modelSettings,
-        messages: options.messages,
-        user: (_a = openAiOptions.executionToolsOptions.userId) === null || _a === void 0 ? void 0 : _a.toString(),
-        tools: options.tools === undefined ? undefined : mapToolsToOpenAi(options.tools),
-    };
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
 }
+
 /**
- * Executes one chat completion turn and returns the parsed response plus measured usage.
+ * This error type indicates that some part of the code is not implemented yet
+ *
+ * @public exported from `@promptbook/core`
  */
-async function executeChatTurn(openAiOptions, options) {
-    if (openAiOptions.executionToolsOptions.isVerbose) {
-        console.info(colors.bgWhite('rawRequest'), JSON.stringify(options.rawRequest, null, 4));
-    }
-    const turnStart = $getCurrentDate();
-    const rawResponse = await openAiOptions.executeRateLimitedRequest(() => options.client.chat.completions.create(options.rawRequest));
-    const turnComplete = $getCurrentDate();
-    if (openAiOptions.executionToolsOptions.isVerbose) {
-        console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
-    }
-    if (!rawResponse.choices[0]) {
-        throw new PipelineExecutionError(`No choises from ${openAiOptions.title}`);
+class NotYetImplementedError extends Error {
+    constructor(message) {
+        super(spaceTrim$1((block) => `
+                    ${block(message)}
+
+                    Note: This feature is not implemented yet but it will be soon.
+
+                    If you want speed up the implementation or just read more, look here:
+                    https://github.com/webgptorg/promptbook
+
+                    Or contact us on pavol@ptbk.io
+
+                `));
+        this.name = 'NotYetImplementedError';
+        Object.setPrototypeOf(this, NotYetImplementedError.prototype);
     }
-    const responseMessage = rawResponse.choices[0].message;
-    const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
-    const usage = openAiOptions.computeUsage(options.promptContent, responseMessage.content || '', rawResponse, duration);
-    return {
-        rawResponse,
-        responseMessage,
-        turnComplete,
-        usage,
-    };
 }
+
 /**
- * Executes all tool calls requested in one assistant response and appends their results to the conversation.
+ * This error indicates that the promptbook in a markdown format cannot be parsed into a valid promptbook object
+ *
+ * @public exported from `@promptbook/core`
  */
-async function handleChatToolCalls(openAiOptions, options) {
-    const requestedToolCalls = options.responseMessage.tool_calls || [];
-    const toolCallStartedAt = new Map();
-    const pendingToolCalls = requestedToolCalls.map((toolCall) => {
-        const calledAt = $getCurrentDate();
-        if (toolCall.id) {
-            toolCallStartedAt.set(toolCall.id, calledAt);
-        }
-        return createPendingChatToolCall({
-            toolCall,
-            functionName: String(toolCall.function.name),
-            functionArguments: toolCall.function.arguments,
-            calledAt,
-        });
-    });
-    emitChatProgress({
-        start: options.start,
-        complete: options.turnComplete,
-        rawPromptContent: options.rawPromptContent,
-        onProgress: options.onProgress,
-        content: options.responseMessage.content || '',
-        modelName: options.rawResponse.model || options.modelName,
-        usage: options.usage,
-        rawRequest: options.rawRequest,
-        rawResponse: options.rawResponse,
-        toolCalls: pendingToolCalls,
-    });
-    await forEachAsync(requestedToolCalls, {}, async (toolCall) => {
-        const completedToolCall = await executeChatToolCall(openAiOptions, {
-            prompt: options.prompt,
-            toolCall,
-            toolCallStartedAt,
-            responseContent: options.responseMessage.content || '',
-            start: options.start,
-            rawPromptContent: options.rawPromptContent,
-            rawRequest: options.rawRequest,
-            rawResponse: options.rawResponse,
-            modelName: options.rawResponse.model || options.modelName,
-            usage: options.usage,
-            messages: options.messages,
-            onProgress: options.onProgress,
-        });
-        options.toolCalls.push(completedToolCall);
-    });
+class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+        Object.setPrototypeOf(this, ParseError.prototype);
+    }
 }
+// TODO: Maybe split `ParseError` and `ApplyError`
+
 /**
- * Creates the initial pending snapshot for one chat tool call.
+ * 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`
  */
-function createPendingChatToolCall(options) {
-    return {
-        name: options.functionName,
-        arguments: options.functionArguments,
-        result: '',
-        rawToolCall: options.toolCall,
-        createdAt: options.calledAt,
-        state: 'PENDING',
-        logs: [
-            createToolCallLogEntry({
-                kind: 'request',
-                title: 'Request prepared',
-                message: `Prepared ${options.functionName} request.`,
-                payload: {
-                    arguments: options.functionArguments,
-                },
-            }),
-        ],
-    };
-}
-/**
- * Executes one tool call requested by the chat response and appends the tool message.
- */
-async function executeChatToolCall(openAiOptions, options) {
-    const functionName = String(options.toolCall.function.name);
-    const functionArguments = options.toolCall.function.arguments;
-    const calledAt = options.toolCall.id
-        ? options.toolCallStartedAt.get(options.toolCall.id) || $getCurrentDate()
-        : $getCurrentDate();
-    const pendingToolCall = createPendingChatToolCall({
-        toolCall: options.toolCall,
-        functionName,
-        functionArguments,
-        calledAt,
-    });
-    const executionResult = await executeChatFunctionTool(openAiOptions, {
-        prompt: options.prompt,
-        start: options.start,
-        rawPromptContent: options.rawPromptContent,
-        onProgress: options.onProgress,
-        content: options.responseContent,
-        rawRequest: options.rawRequest,
-        rawResponse: options.rawResponse,
-        modelName: options.modelName,
-        usage: options.usage,
-        functionName,
-        functionArguments,
-        pendingToolCall,
-    });
-    options.messages.push({
-        role: 'tool',
-        tool_call_id: options.toolCall.id,
-        content: executionResult.assistantVisibleFunctionResponse,
-    });
-    const completedToolCall = createCompletedChatToolCall({
-        toolCall: options.toolCall,
-        functionName,
-        calledAt,
-        currentToolCallSnapshot: executionResult.currentToolCallSnapshot,
-        toolResult: executionResult.toolResult,
-        errors: executionResult.errors,
-    });
-    emitChatProgress({
-        start: options.start,
-        rawPromptContent: options.rawPromptContent,
-        onProgress: options.onProgress,
-        content: options.responseContent,
-        modelName: options.modelName,
-        usage: options.usage,
-        rawRequest: options.rawRequest,
-        rawResponse: options.rawResponse,
-        toolCalls: [completedToolCall],
-    });
-    return completedToolCall;
+class PipelineLogicError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineLogicError';
+        Object.setPrototypeOf(this, PipelineLogicError.prototype);
+    }
 }
+
 /**
- * Resolves the configured script tools for chat tool execution.
+ * This error indicates errors in referencing promptbooks between each other
+ *
+ * @public exported from `@promptbook/core`
  */
-function resolveChatScriptTools(openAiOptions, functionName) {
-    const executionTools = openAiOptions.executionToolsOptions.executionTools;
-    if (!executionTools || !executionTools.script) {
-        throw new PipelineExecutionError(`Model requested tool '${functionName}' but no executionTools.script were provided in OpenAiCompatibleExecutionTools options`);
+class PipelineUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PipelineUrlError';
+        Object.setPrototypeOf(this, PipelineUrlError.prototype);
     }
-    return Array.isArray(executionTools.script) ? executionTools.script : [executionTools.script];
 }
+
 /**
- * Executes the configured script tool for one chat-requested function call.
+ * Error thrown when a fetch request fails
+ *
+ * @public exported from `@promptbook/core`
  */
-async function executeChatFunctionTool(openAiOptions, options) {
-    const scriptTools = resolveChatScriptTools(openAiOptions, options.functionName);
-    let functionResponse;
-    let assistantVisibleFunctionResponse;
-    let toolResult;
-    let errors;
-    let currentToolCallSnapshot = options.pendingToolCall;
-    try {
-        const scriptTool = scriptTools[0];
-        const progressListenerToken = registerToolCallProgressListener((update) => {
-            currentToolCallSnapshot = applyToolCallProgressUpdate(currentToolCallSnapshot, update);
-            emitChatProgress({
-                start: options.start,
-                rawPromptContent: options.rawPromptContent,
-                onProgress: options.onProgress,
-                content: options.content,
-                modelName: options.modelName,
-                usage: options.usage,
-                rawRequest: options.rawRequest,
-                rawResponse: options.rawResponse,
-                toolCalls: [currentToolCallSnapshot],
-            });
-        });
-        try {
-            functionResponse = await scriptTool.execute({
-                scriptLanguage: 'javascript',
-                script: buildToolInvocationScript({
-                    functionName: options.functionName,
-                    functionArgsExpression: options.functionArguments,
-                }),
-                parameters: {
-                    ...options.prompt.parameters,
-                    [TOOL_PROGRESS_TOKEN_PARAMETER]: progressListenerToken,
-                },
-            });
-        }
-        finally {
-            unregisterToolCallProgressListener(progressListenerToken);
-        }
-        const toolExecutionEnvelope = parseToolExecutionEnvelope(functionResponse);
-        assistantVisibleFunctionResponse = (toolExecutionEnvelope === null || toolExecutionEnvelope === void 0 ? void 0 : toolExecutionEnvelope.assistantMessage) || functionResponse;
-        toolResult =
-            toolExecutionEnvelope !== null && toolExecutionEnvelope !== undefined
-                ? toolExecutionEnvelope.toolResult
-                : functionResponse;
-    }
-    catch (error) {
-        assertsError(error);
-        functionResponse = `Error: ${error.message}`;
-        assistantVisibleFunctionResponse = functionResponse;
-        toolResult = functionResponse;
-        errors = [serializeError(error)];
+class PromptbookFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptbookFetchError';
+        Object.setPrototypeOf(this, PromptbookFetchError.prototype);
     }
-    return {
-        assistantVisibleFunctionResponse,
-        currentToolCallSnapshot,
-        errors,
-        toolResult,
-    };
 }
+
 /**
- * Finalizes one chat tool-call snapshot after execution ends.
+ * Index of all custom errors
+ *
+ * @public exported from `@promptbook/core`
  */
-function createCompletedChatToolCall(options) {
-    const hasErrors = options.errors !== undefined && options.errors.length > 0;
-    return {
-        ...options.currentToolCallSnapshot,
-        result: options.toolResult,
-        rawToolCall: options.toolCall,
-        createdAt: options.calledAt,
-        errors: options.errors,
-        state: resolveFinalToolCallState({
-            currentState: options.currentToolCallSnapshot.state,
-            errors: options.errors,
-        }),
-        logs: [
-            ...(options.currentToolCallSnapshot.logs || []),
-            createToolCallLogEntry({
-                kind: hasErrors ? 'error' : 'result',
-                level: hasErrors ? 'error' : 'info',
-                title: hasErrors ? 'Execution failed' : 'Execution finished',
-                message: hasErrors
-                    ? `${options.functionName} failed before returning a final result.`
-                    : `${options.functionName} returned a result.`,
-            }),
-        ],
-    };
-}
+const PROMPTBOOK_ERRORS = {
+    AbstractFormatError,
+    CsvFormatError,
+    CollectionError,
+    EnvironmentMismatchError,
+    ExpectError,
+    KnowledgeScrapeError,
+    LimitReachedError,
+    MissingToolsError,
+    NotFoundError,
+    NotYetImplementedError,
+    ParseError,
+    PipelineExecutionError,
+    PipelineLogicError,
+    PipelineUrlError,
+    AuthenticationError,
+    PromptbookFetchError,
+    UnexpectedError,
+    WrappedError,
+    NotAllowed,
+    DatabaseError,
+    ConflictError,
+    // TODO: [🪑]> VersionMismatchError,
+};
 /**
- * Emits one chat progress chunk with shared timing, request metadata, and tool-call snapshots.
+ * Index of all javascript errors
+ *
+ * @private for internal usage
  */
-function emitChatProgress(options) {
-    options.onProgress({
-        content: options.content,
-        modelName: options.modelName,
-        timing: {
-            start: options.start,
-            complete: options.complete || $getCurrentDate(),
-        },
-        usage: options.usage,
-        toolCalls: options.toolCalls,
-        rawPromptContent: options.rawPromptContent,
-        rawRequest: options.rawRequest,
-        rawResponse: options.rawResponse,
-    });
-}
+const COMMON_JAVASCRIPT_ERRORS = {
+    Error,
+    EvalError,
+    RangeError,
+    ReferenceError,
+    SyntaxError,
+    TypeError,
+    URIError,
+    AggregateError,
+    /*
+  Note: Not widely supported
+  > InternalError,
+  > ModuleError,
+  > HeapError,
+  > WebAssemblyCompileError,
+  > WebAssemblyRuntimeError,
+  */
+};
 /**
- * Creates the final chat prompt result after the tool loop has finished.
+ * Index of all errors
+ *
+ * @private for internal usage
  */
-function createChatPromptResult(openAiOptions, options) {
-    const resultContent = options.responseMessage.content;
-    if (resultContent === null) {
-        throw new PipelineExecutionError(`No response message from ${openAiOptions.title}`);
-    }
-    return exportJson({
-        name: 'promptResult',
-        message: `Result of \`OpenAiCompatibleExecutionTools.callChatModel\``,
-        order: [],
-        value: {
-            content: resultContent,
-            modelName: options.rawResponse.model || options.modelName,
-            timing: {
-                start: options.start,
-                complete: options.complete,
-            },
-            usage: options.usage,
-            toolCalls: options.toolCalls,
-            rawPromptContent: options.rawPromptContent,
-            rawRequest: options.rawRequest,
-            rawResponse: options.rawResponse,
-        },
-    });
-}
+const ALL_ERRORS = {
+    ...PROMPTBOOK_ERRORS,
+    ...COMMON_JAVASCRIPT_ERRORS,
+};
+// Note: [💞] Ignore a discrepancy between file name and entity name
 
 /**
- * Creates a deep clone of JSON-serializable prompt payloads.
+ * Serializes an error into a [🚉] JSON-serializable object
+ *
+ * @public exported from `@promptbook/utils`
  */
-function cloneSerializableValue(value) {
-    return JSON.parse(JSON.stringify(value));
+function serializeError(error) {
+    const { name, message, stack } = error;
+    const { id } = error;
+    if (!Object.keys(ALL_ERRORS).includes(name)) {
+        console.error(spaceTrim$1((block) => `
+
+                    Cannot serialize error with name "${name}"
+
+                    Authors of Promptbook probably forgot to add this error into the list of errors:
+                    https://github.com/webgptorg/promptbook/blob/main/src/errors/0-index.ts
+
+
+                    ${block(stack || message)}
+
+                `));
+    }
+    return {
+        name: name,
+        message,
+        stack,
+        id, // Include id in the serialized object
+    };
 }
+
 /**
- * Execution Tools for calling OpenAI API or other OpenAI compatible provider
+ * Async version of Array.forEach
  *
- * @public exported from `@promptbook/openai`
+ * @param array - Array to iterate over
+ * @param options - Options for the function
+ * @param callbackfunction - Function to call for each item
+ * @deprecated [🪂] Use queues instead
+ *
+ * @public exported from `@promptbook/utils`
  */
-class OpenAiCompatibleExecutionTools {
-    // Removed retriedUnsupportedParameters and attemptHistory instance fields
-    /**
-     * Creates OpenAI compatible Execution Tools.
-     *
-     * @param options which are relevant are directly passed to the OpenAI compatible client
-     */
-    constructor(options) {
-        this.options = options;
-        /**
-         * OpenAI API client.
-         */
-        this.client = null;
-        // TODO: Allow configuring rate limits via options
-        this.limiter = new Bottleneck({
-            minTime: 60000 / (this.options.maxRequestsPerMinute || DEFAULT_MAX_REQUESTS_PER_MINUTE),
+async function forEachAsync(array, options, callbackfunction) {
+    const { maxParallelCount = Infinity } = options;
+    let index = 0;
+    let runningTasks = [];
+    const tasks = [];
+    for (const item of array) {
+        const currentIndex = index++;
+        const task = callbackfunction(item, currentIndex, array);
+        tasks.push(task);
+        runningTasks.push(task);
+        /* not await */ Promise.resolve(task).then(() => {
+            runningTasks = runningTasks.filter((runningTask) => runningTask !== task);
         });
-    }
-    async getClient() {
-        if (this.client === null) {
-            // Note: Passing only OpenAI relevant options to OpenAI constructor
-            const openAiOptions = { ...this.options };
-            delete openAiOptions.isVerbose;
-            delete openAiOptions.userId;
-            // Enhanced configuration with retries and timeouts.
-            const enhancedOptions = {
-                ...openAiOptions,
-                timeout: API_REQUEST_TIMEOUT,
-                maxRetries: CONNECTION_RETRIES_LIMIT,
-            };
-            this.client = new OpenAI(enhancedOptions);
+        if (maxParallelCount < runningTasks.length) {
+            await Promise.race(runningTasks);
         }
-        return this.client;
     }
-    /**
-     * Check the `options` passed to `constructor`
-     */
-    async checkConfiguration() {
-        await this.getClient();
-        // TODO: [🎍] Do here a real check that API is online, working and API key is correct
+    await Promise.all(tasks);
+}
+
+/**
+ * Builds a tool invocation script that injects hidden runtime context into tool args.
+ *
+ * @private utility of OpenAI tool execution wrappers
+ */
+function buildToolInvocationScript(options) {
+    const { functionName, functionArgsExpression } = options;
+    return `
+        const args = ${functionArgsExpression};
+        const runtimeContextRaw =
+            typeof ${TOOL_RUNTIME_CONTEXT_PARAMETER} === 'undefined'
+                ? undefined
+                : ${TOOL_RUNTIME_CONTEXT_PARAMETER};
+
+        if (runtimeContextRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+            args.${TOOL_RUNTIME_CONTEXT_ARGUMENT} = runtimeContextRaw;
+        }
+
+        const toolProgressTokenRaw =
+            typeof ${TOOL_PROGRESS_TOKEN_PARAMETER} === 'undefined'
+                ? undefined
+                : ${TOOL_PROGRESS_TOKEN_PARAMETER};
+
+        if (toolProgressTokenRaw !== undefined && args && typeof args === 'object' && !Array.isArray(args)) {
+            args.${TOOL_PROGRESS_TOKEN_ARGUMENT} = toolProgressTokenRaw;
+        }
+
+        return await ${functionName}(args);
+    `;
+}
+
+/**
+ * Executes chat-requested tools and keeps their progress snapshots in sync with streamed progress updates.
+ *
+ * @private helper of `callOpenAiCompatibleChatModel`
+ */
+class OpenAiCompatibleChatToolCaller {
+    constructor(options) {
+        this.options = options;
     }
     /**
-     * List all available OpenAI compatible models that can be used
+     * Executes all tool calls requested in one assistant response and appends their results to the conversation.
      */
-    async listModels() {
-        const client = await this.getClient();
-        const rawModelsList = await client.models.list();
-        const availableModels = rawModelsList.data
-            .sort((a, b) => (a.created > b.created ? 1 : -1))
-            .map((modelFromApi) => {
-            const modelFromList = this.HARDCODED_MODELS.find(({ modelName }) => modelName === modelFromApi.id ||
-                modelName.startsWith(modelFromApi.id) ||
-                modelFromApi.id.startsWith(modelName));
-            if (modelFromList !== undefined) {
-                return modelFromList;
+    async handleToolCalls(options) {
+        const requestedToolCalls = options.responseMessage.tool_calls || [];
+        const toolCallStartedAt = new Map();
+        const pendingToolCalls = requestedToolCalls.map((toolCall) => {
+            const calledAt = $getCurrentDate();
+            if (toolCall.id) {
+                toolCallStartedAt.set(toolCall.id, calledAt);
             }
-            return {
-                modelVariant: 'CHAT',
-                modelTitle: modelFromApi.id,
-                modelName: modelFromApi.id,
-                modelDescription: '',
-            };
+            return this.options.progressReporter.createPendingToolCall({
+                toolCall,
+                functionName: String(toolCall.function.name),
+                functionArguments: toolCall.function.arguments,
+                calledAt,
+            });
         });
-        return availableModels;
-    }
-    /**
-     * Calls OpenAI compatible API to use a chat model.
-     */
-    /**
-     * Calls OpenAI compatible API to use a chat model.
-     */
-    async callChatModel(prompt) {
-        return this.callChatModelStream(prompt, () => { });
-    }
-    /**
-     * Calls OpenAI compatible API to use a chat model with streaming.
-     */
-    async callChatModelStream(prompt, onProgress, _options) {
-        return callOpenAiCompatibleChatModel({
-            prompt,
-            onProgress,
-            title: this.title,
-            executionToolsOptions: this.options,
-            getClient: () => this.getClient(),
-            executeRateLimitedRequest: (requestFn) => this.executeRateLimitedRequest(requestFn),
-            computeUsage: (...usageArguments) => this.computeUsage(...usageArguments),
-            getDefaultChatModel: () => this.getDefaultChatModel(),
+        this.options.progressReporter.emitProgress({
+            start: options.start,
+            complete: options.turnComplete,
+            rawPromptContent: options.rawPromptContent,
+            onProgress: options.onProgress,
+            content: options.responseMessage.content || '',
+            modelName: options.rawResponse.model || options.modelName,
+            usage: options.usage,
+            rawRequest: options.rawRequest,
+            rawResponse: options.rawResponse,
+            toolCalls: pendingToolCalls,
+        });
+        await forEachAsync(requestedToolCalls, {}, async (toolCall) => {
+            const completedToolCall = await this.executeToolCall({
+                prompt: options.prompt,
+                toolCall,
+                toolCallStartedAt,
+                responseContent: options.responseMessage.content || '',
+                start: options.start,
+                rawPromptContent: options.rawPromptContent,
+                rawRequest: options.rawRequest,
+                rawResponse: options.rawResponse,
+                modelName: options.rawResponse.model || options.modelName,
+                usage: options.usage,
+                messages: options.messages,
+                onProgress: options.onProgress,
+            });
+            options.toolCalls.push(completedToolCall);
         });
     }
     /**
-     * Executes one OpenAI request under the shared rate limiter and network retry policy.
+     * Executes one tool call requested by the chat response and appends the tool message.
      */
-    async executeRateLimitedRequest(requestFn) {
-        return this.limiter
-            .schedule(() => this.makeRequestWithNetworkRetry(requestFn))
-            .catch((error) => {
-            assertsError(error);
-            if (this.options.isVerbose) {
-                console.info(colors.bgRed('error'), error);
-            }
-            throw error;
+    async executeToolCall(options) {
+        const functionName = String(options.toolCall.function.name);
+        const functionArguments = options.toolCall.function.arguments;
+        const calledAt = options.toolCall.id
+            ? options.toolCallStartedAt.get(options.toolCall.id) || $getCurrentDate()
+            : $getCurrentDate();
+        const pendingToolCall = this.options.progressReporter.createPendingToolCall({
+            toolCall: options.toolCall,
+            functionName,
+            functionArguments,
+            calledAt,
         });
+        const executionResult = await this.executeFunctionTool({
+            prompt: options.prompt,
+            start: options.start,
+            rawPromptContent: options.rawPromptContent,
+            onProgress: options.onProgress,
+            content: options.responseContent,
+            rawRequest: options.rawRequest,
+            rawResponse: options.rawResponse,
+            modelName: options.modelName,
+            usage: options.usage,
+            functionName,
+            functionArguments,
+            pendingToolCall,
+        });
+        options.messages.push({
+            role: 'tool',
+            tool_call_id: options.toolCall.id,
+            content: executionResult.assistantVisibleFunctionResponse,
+        });
+        const completedToolCall = this.options.progressReporter.createCompletedToolCall({
+            toolCall: options.toolCall,
+            functionName,
+            calledAt,
+            currentToolCallSnapshot: executionResult.currentToolCallSnapshot,
+            toolResult: executionResult.toolResult,
+            errors: executionResult.errors,
+        });
+        this.options.progressReporter.emitProgress({
+            start: options.start,
+            rawPromptContent: options.rawPromptContent,
+            onProgress: options.onProgress,
+            content: options.responseContent,
+            modelName: options.modelName,
+            usage: options.usage,
+            rawRequest: options.rawRequest,
+            rawResponse: options.rawResponse,
+            toolCalls: [completedToolCall],
+        });
+        return completedToolCall;
     }
     /**
-     * Calls OpenAI API to use a complete model.
+     * Resolves the configured script tools for chat tool execution.
      */
-    async callCompletionModel(prompt) {
-        const clonedPrompt = cloneSerializableValue(prompt);
-        return this.callCompletionModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
+    resolveScriptTools(functionName) {
+        const executionTools = this.options.executionToolsOptions.executionTools;
+        if (!executionTools || !executionTools.script) {
+            throw new PipelineExecutionError(`Model requested tool '${functionName}' but no executionTools.script were provided in OpenAiCompatibleExecutionTools options`);
+        }
+        return Array.isArray(executionTools.script) ? executionTools.script : [executionTools.script];
     }
     /**
-     * Internal method that handles parameter retry for completion model calls
+     * Executes the configured script tool for one chat-requested function call.
      */
-    async callCompletionModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
-        var _a;
-        if (this.options.isVerbose) {
-            console.info(`🖋 ${this.title} callCompletionModel call`, { prompt, currentModelRequirements });
-        }
-        const { content, parameters } = prompt;
-        const client = await this.getClient();
-        // TODO: [☂] Use here more modelRequirements
-        if (currentModelRequirements.modelVariant !== 'COMPLETION') {
-            throw new PipelineExecutionError('Use callCompletionModel only for COMPLETION variant');
-        }
-        const modelName = currentModelRequirements.modelName || this.getDefaultCompletionModel().modelName;
-        const modelSettings = {
-            model: modelName,
-            max_tokens: currentModelRequirements.maxTokens,
-            temperature: currentModelRequirements.temperature,
-        };
-        const rawPromptContent = templateParameters(content, { ...parameters, modelName });
-        const rawRequest = {
-            ...modelSettings,
-            model: modelName,
-            prompt: rawPromptContent,
-            user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
-        };
-        const start = $getCurrentDate();
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
-        }
+    async executeFunctionTool(options) {
+        const scriptTools = this.resolveScriptTools(options.functionName);
+        let functionResponse;
+        let assistantVisibleFunctionResponse;
+        let toolResult;
+        let errors;
+        let currentToolCallSnapshot = options.pendingToolCall;
         try {
-            const turnStart = $getCurrentDate();
-            const rawResponse = await this.executeRateLimitedRequest(() => client.completions.create(rawRequest));
-            const turnComplete = $getCurrentDate();
-            if (this.options.isVerbose) {
-                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
-            }
-            if (!rawResponse.choices[0]) {
-                throw new PipelineExecutionError(`No choises from ${this.title}`);
+            const scriptTool = scriptTools[0];
+            const progressListenerToken = registerToolCallProgressListener((update) => {
+                currentToolCallSnapshot = this.options.progressReporter.applyToolCallProgressUpdate(currentToolCallSnapshot, update);
+                this.options.progressReporter.emitProgress({
+                    start: options.start,
+                    rawPromptContent: options.rawPromptContent,
+                    onProgress: options.onProgress,
+                    content: options.content,
+                    modelName: options.modelName,
+                    usage: options.usage,
+                    rawRequest: options.rawRequest,
+                    rawResponse: options.rawResponse,
+                    toolCalls: [currentToolCallSnapshot],
+                });
+            });
+            try {
+                functionResponse = await scriptTool.execute({
+                    scriptLanguage: 'javascript',
+                    script: buildToolInvocationScript({
+                        functionName: options.functionName,
+                        functionArgsExpression: options.functionArguments,
+                    }),
+                    parameters: {
+                        ...options.prompt.parameters,
+                        [TOOL_PROGRESS_TOKEN_PARAMETER]: progressListenerToken,
+                    },
+                });
             }
-            if (rawResponse.choices.length > 1) {
-                throw new PipelineExecutionError(`More than one choise from ${this.title}`);
+            finally {
+                unregisterToolCallProgressListener(progressListenerToken);
             }
-            const resultContent = rawResponse.choices[0].text;
-            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
-            const usage = this.computeUsage(content || '', resultContent || '', rawResponse, duration);
-            return exportJson({
-                name: 'promptResult',
-                message: `Result of \`OpenAiCompatibleExecutionTools.callCompletionModel\``,
-                order: [],
-                value: {
-                    content: resultContent,
-                    modelName: rawResponse.model || modelName,
-                    timing: {
-                        start,
-                        complete: turnComplete,
-                    },
-                    usage,
-                    rawPromptContent,
-                    rawRequest,
-                    rawResponse,
-                },
-            });
+            const toolExecutionEnvelope = parseToolExecutionEnvelope(functionResponse);
+            assistantVisibleFunctionResponse = (toolExecutionEnvelope === null || toolExecutionEnvelope === void 0 ? void 0 : toolExecutionEnvelope.assistantMessage) || functionResponse;
+            toolResult =
+                toolExecutionEnvelope !== null && toolExecutionEnvelope !== undefined
+                    ? toolExecutionEnvelope.toolResult
+                    : functionResponse;
         }
         catch (error) {
             assertsError(error);
-            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
-                error,
-                modelName,
-                currentModelRequirements,
-            });
-            return this.callCompletionModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
+            functionResponse = `Error: ${error.message}`;
+            assistantVisibleFunctionResponse = functionResponse;
+            toolResult = functionResponse;
+            errors = [serializeError(error)];
         }
+        return {
+            assistantVisibleFunctionResponse,
+            currentToolCallSnapshot,
+            errors,
+            toolResult,
+        };
     }
-    /**
-     * Calls OpenAI compatible API to use a embedding model
-     */
-    async callEmbeddingModel(prompt) {
-        const clonedPrompt = cloneSerializableValue(prompt);
-        return this.callEmbeddingModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
+}
+
+/**
+ * Calls the OpenAI-compatible chat model flow, including tool execution and unsupported-parameter retries.
+ *
+ * @private function of `OpenAiCompatibleExecutionTools`
+ */
+async function callOpenAiCompatibleChatModel(options) {
+    const chatPromptBuilder = new OpenAiCompatibleChatPromptBuilder();
+    const chatProgressReporter = new OpenAiCompatibleChatProgressReporter();
+    const chatToolCaller = new OpenAiCompatibleChatToolCaller({
+        executionToolsOptions: options.executionToolsOptions,
+        progressReporter: chatProgressReporter,
+    });
+    const clonedPrompt = chatPromptBuilder.clonePromptPreservingFiles(options.prompt);
+    const unsupportedParameterRetrier = new OpenAiCompatibleUnsupportedParameterRetrier(options.executionToolsOptions.isVerbose);
+    return callChatModelWithRetry({
+        options,
+        prompt: clonedPrompt,
+        currentModelRequirements: clonedPrompt.modelRequirements,
+        unsupportedParameterRetrier,
+        chatPromptBuilder,
+        chatProgressReporter,
+        chatToolCaller,
+    });
+}
+/**
+ * Retries the chat flow when OpenAI-compatible providers reject unsupported parameters.
+ */
+async function callChatModelWithRetry(options) {
+    if (options.options.executionToolsOptions.isVerbose) {
+        console.info(`💬 ${options.options.title} callChatModel call`, {
+            prompt: options.prompt,
+            currentModelRequirements: options.currentModelRequirements,
+        });
     }
-    /**
-     * Internal method that handles parameter retry for embedding model calls
-     */
-    async callEmbeddingModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
-        if (this.options.isVerbose) {
-            console.info(`🖋 ${this.title} embedding call`, { prompt, currentModelRequirements });
-        }
-        const { content, parameters } = prompt;
-        const client = await this.getClient();
-        if (currentModelRequirements.modelVariant !== 'EMBEDDING') {
-            throw new PipelineExecutionError('Use embed only for EMBEDDING variant');
-        }
-        const modelName = currentModelRequirements.modelName || this.getDefaultEmbeddingModel().modelName;
-        const rawPromptContent = templateParameters(content, { ...parameters, modelName });
-        const rawRequest = {
-            input: rawPromptContent,
-            model: modelName,
-        };
-        const start = $getCurrentDate();
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
-        }
+    const { content, parameters, format } = options.prompt;
+    if (options.currentModelRequirements.modelVariant !== 'CHAT') {
+        throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
+    }
+    const modelName = options.currentModelRequirements.modelName || options.options.getDefaultChatModel().modelName;
+    const rawPromptContent = templateParameters(content, { ...parameters, modelName });
+    const modelSettings = options.chatPromptBuilder.createModelSettings({
+        currentModelRequirements: options.currentModelRequirements,
+        format,
+        modelName,
+    });
+    const messages = await options.chatPromptBuilder.createMessages({
+        prompt: options.prompt,
+        currentModelRequirements: options.currentModelRequirements,
+        rawPromptContent,
+    });
+    const client = await options.options.getClient();
+    let totalUsage = options.chatProgressReporter.createEmptyUsage();
+    const toolCalls = [];
+    const start = $getCurrentDate();
+    const tools = 'tools' in options.prompt && Array.isArray(options.prompt.tools)
+        ? options.prompt.tools
+        : options.currentModelRequirements.tools;
+    let isToolCallingLoopActive = true;
+    while (isToolCallingLoopActive) {
+        const rawRequest = options.chatPromptBuilder.createRawRequest({
+            modelSettings,
+            messages,
+            tools,
+            userId: options.options.executionToolsOptions.userId,
+        });
         try {
-            const turnStart = $getCurrentDate();
-            const rawResponse = await this.executeRateLimitedRequest(() => client.embeddings.create(rawRequest));
-            const turnComplete = $getCurrentDate();
-            if (this.options.isVerbose) {
-                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
-            }
-            if (rawResponse.data.length !== 1) {
-                throw new PipelineExecutionError(`Expected exactly 1 data item in response, got ${rawResponse.data.length}`);
-            }
-            const resultContent = rawResponse.data[0].embedding;
-            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
-            const usage = this.computeUsage(content || '', '', rawResponse, duration);
-            return exportJson({
-                name: 'promptResult',
-                message: `Result of \`OpenAiCompatibleExecutionTools.callEmbeddingModel\``,
-                order: [],
-                value: {
-                    content: resultContent,
-                    modelName: rawResponse.model || modelName,
-                    timing: {
-                        start,
-                        complete: turnComplete,
-                    },
-                    usage,
+            const turnResult = await executeChatTurn(options.options, {
+                client,
+                rawRequest,
+                promptContent: content || '',
+            });
+            messages.push(turnResult.responseMessage);
+            totalUsage = addUsage(totalUsage, turnResult.usage);
+            if (turnResult.responseMessage.tool_calls && turnResult.responseMessage.tool_calls.length > 0) {
+                await options.chatToolCaller.handleToolCalls({
+                    prompt: options.prompt,
+                    start,
+                    turnComplete: turnResult.turnComplete,
                     rawPromptContent,
+                    responseMessage: turnResult.responseMessage,
                     rawRequest,
-                    rawResponse,
-                },
+                    rawResponse: turnResult.rawResponse,
+                    modelName,
+                    usage: totalUsage,
+                    toolCalls,
+                    messages,
+                    onProgress: options.options.onProgress,
+                });
+                continue;
+            }
+            isToolCallingLoopActive = false;
+            return options.chatProgressReporter.createChatPromptResult({
+                title: options.options.title,
+                responseMessage: turnResult.responseMessage,
+                rawPromptContent,
+                rawRequest,
+                rawResponse: turnResult.rawResponse,
+                modelName,
+                start,
+                complete: $getCurrentDate(),
+                usage: totalUsage,
+                toolCalls,
             });
         }
         catch (error) {
+            isToolCallingLoopActive = false;
             assertsError(error);
-            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
-                error,
-                modelName,
-                currentModelRequirements,
+            return callChatModelWithRetry({
+                ...options,
+                currentModelRequirements: options.unsupportedParameterRetrier.resolveRetryOrThrow({
+                    error,
+                    modelName,
+                    currentModelRequirements: options.currentModelRequirements,
+                }),
             });
-            return this.callEmbeddingModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
         }
     }
+    throw new PipelineExecutionError(`Tool calling loop did not return a result from ${options.options.title}`);
+}
+/**
+ * Executes one chat completion turn and returns the parsed response plus measured usage.
+ */
+async function executeChatTurn(openAiOptions, options) {
+    if (openAiOptions.executionToolsOptions.isVerbose) {
+        console.info(colors.bgWhite('rawRequest'), JSON.stringify(options.rawRequest, null, 4));
+    }
+    const turnStart = $getCurrentDate();
+    const rawResponse = await openAiOptions.executeRateLimitedRequest(() => options.client.chat.completions.create(options.rawRequest));
+    const turnComplete = $getCurrentDate();
+    if (openAiOptions.executionToolsOptions.isVerbose) {
+        console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
+    }
+    if (!rawResponse.choices[0]) {
+        throw new PipelineExecutionError(`No choises from ${openAiOptions.title}`);
+    }
+    const responseMessage = rawResponse.choices[0].message;
+    const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
+    const usage = openAiOptions.computeUsage(options.promptContent, responseMessage.content || '', rawResponse, duration);
+    return {
+        rawResponse,
+        responseMessage,
+        turnComplete,
+        usage,
+    };
+}
+
+/**
+ * Execution Tools for calling OpenAI API or other OpenAI compatible provider
+ *
+ * @public exported from `@promptbook/openai`
+ */
+class OpenAiCompatibleExecutionTools {
     /**
-     * Calls OpenAI compatible API to use a image generation model
+     * Creates OpenAI compatible Execution Tools.
+     *
+     * @param options which are relevant are directly passed to the OpenAI compatible client
      */
-    async callImageGenerationModel(prompt) {
-        const clonedPrompt = cloneSerializableValue(prompt);
-        return this.callImageGenerationModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, new OpenAiCompatibleUnsupportedParameterRetrier(this.options.isVerbose));
+    constructor(options) {
+        this.options = options;
+        this.requestManager = new OpenAiCompatibleRequestManager(this.options);
+        this.modelCatalog = new OpenAiCompatibleModelCatalog({
+            getTitle: () => this.title,
+            getClient: () => this.getClient(),
+            getHardcodedModels: () => this.HARDCODED_MODELS,
+        });
+        this.nonChatPromptCaller = new OpenAiCompatibleNonChatPromptCaller({
+            getTitle: () => this.title,
+            isVerbose: this.options.isVerbose,
+            userId: this.options.userId,
+            getClient: () => this.getClient(),
+            executeRateLimitedRequest: (requestFn) => this.executeRateLimitedRequest(requestFn),
+            computeUsage: (...usageArguments) => this.computeUsage(...usageArguments),
+            getDefaultCompletionModel: () => this.getDefaultCompletionModel(),
+            getDefaultEmbeddingModel: () => this.getDefaultEmbeddingModel(),
+            getDefaultImageGenerationModel: () => this.getDefaultImageGenerationModel(),
+            getHardcodedModels: () => this.HARDCODED_MODELS,
+        });
+    }
+    async getClient() {
+        return this.requestManager.getClient();
     }
     /**
-     * Internal method that handles parameter retry for image generation model calls
+     * Check the `options` passed to `constructor`
      */
-    async callImageGenerationModelWithRetry(prompt, currentModelRequirements, unsupportedParameterRetrier) {
-        var _a, _b;
-        if (this.options.isVerbose) {
-            console.info(`🎨 ${this.title} callImageGenerationModel call`, { prompt, currentModelRequirements });
-        }
-        const { content, parameters } = prompt;
-        const client = await this.getClient();
-        // TODO: [☂] Use here more modelRequirements
-        if (currentModelRequirements.modelVariant !== 'IMAGE_GENERATION') {
-            throw new PipelineExecutionError('Use callImageGenerationModel only for IMAGE_GENERATION variant');
-        }
-        const modelName = currentModelRequirements.modelName || this.getDefaultImageGenerationModel().modelName;
-        const modelSettings = {
-            model: modelName,
-            size: currentModelRequirements.size,
-            quality: currentModelRequirements.quality,
-            style: currentModelRequirements.style,
-        };
-        let rawPromptContent = templateParameters(content, { ...parameters, modelName });
-        if ('attachments' in prompt && Array.isArray(prompt.attachments) && prompt.attachments.length > 0) {
-            rawPromptContent +=
-                '\n\n' +
-                    prompt.attachments.map((attachment) => `Image attachment: ${attachment.url}`).join('\n');
-        }
-        const rawRequest = {
-            ...modelSettings,
-            prompt: rawPromptContent,
-            size: modelSettings.size || '1024x1024',
-            user: (_a = this.options.userId) === null || _a === void 0 ? void 0 : _a.toString(),
-            response_format: 'url', // TODO: [🧠] Maybe allow b64_json
-        };
-        const start = $getCurrentDate();
-        if (this.options.isVerbose) {
-            console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
-        }
-        try {
-            const turnStart = $getCurrentDate();
-            const rawResponse = await this.executeRateLimitedRequest(() => client.images.generate(rawRequest));
-            const turnComplete = $getCurrentDate();
-            if (this.options.isVerbose) {
-                console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
-            }
-            if (!rawResponse.data[0]) {
-                throw new PipelineExecutionError(`No choises from ${this.title}`);
-            }
-            if (rawResponse.data.length > 1) {
-                throw new PipelineExecutionError(`More than one choise from ${this.title}`);
-            }
-            const resultContent = rawResponse.data[0].url;
-            const modelInfo = this.HARDCODED_MODELS.find((model) => model.modelName === modelName);
-            const price = ((_b = modelInfo === null || modelInfo === void 0 ? void 0 : modelInfo.pricing) === null || _b === void 0 ? void 0 : _b.output) ? uncertainNumber(modelInfo.pricing.output) : uncertainNumber();
-            const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
-            return exportJson({
-                name: 'promptResult',
-                message: `Result of \`OpenAiCompatibleExecutionTools.callImageGenerationModel\``,
-                order: [],
-                value: {
-                    content: resultContent,
-                    modelName: modelName,
-                    timing: {
-                        start,
-                        complete: turnComplete,
-                    },
-                    usage: {
-                        price,
-                        duration,
-                        input: {
-                            tokensCount: uncertainNumber(0),
-                            ...computeUsageCounts(rawPromptContent),
-                        },
-                        output: {
-                            tokensCount: uncertainNumber(0),
-                            ...computeUsageCounts(''),
-                        },
-                    },
-                    rawPromptContent,
-                    rawRequest,
-                    rawResponse,
-                },
-            });
-        }
-        catch (error) {
-            assertsError(error);
-            const modifiedModelRequirements = unsupportedParameterRetrier.resolveRetryOrThrow({
-                error,
-                modelName,
-                currentModelRequirements,
-            });
-            return this.callImageGenerationModelWithRetry(prompt, modifiedModelRequirements, unsupportedParameterRetrier);
-        }
+    async checkConfiguration() {
+        await this.getClient();
+        // TODO: [🎍] Do here a real check that API is online, working and API key is correct
     }
-    // <- Note: [🤖] callXxxModel
     /**
-     * Get the model that should be used as default
+     * List all available OpenAI compatible models that can be used
      */
-    getDefaultModel(defaultModelName) {
-        // Note: Match exact or prefix for model families
-        const model = this.HARDCODED_MODELS.find(({ modelName }) => modelName === defaultModelName || modelName.startsWith(defaultModelName));
-        if (model === undefined) {
-            throw new PipelineExecutionError(spaceTrim$1((block) => `
-                            Cannot find model in ${this.title} models with name "${defaultModelName}" which should be used as default.
-
-                            Available models:
-                            ${block(this.HARDCODED_MODELS.map(({ modelName }) => `- "${modelName}"`).join('\n'))}
-
-                            Model "${defaultModelName}" is probably not available anymore, not installed, inaccessible or misconfigured.
-
-                        `));
-        }
-        return model;
+    async listModels() {
+        return this.modelCatalog.listModels();
     }
-    // <- Note: [🤖] getDefaultXxxModel
     /**
-     * Makes a request with retry logic for network errors like ECONNRESET
+     * Calls OpenAI compatible API to use a chat model.
      */
-    async makeRequestWithNetworkRetry(requestFn) {
-        let lastError;
-        for (let attempt = 1; attempt <= CONNECTION_RETRIES_LIMIT; attempt++) {
-            try {
-                return await requestFn();
-            }
-            catch (error) {
-                assertsError(error);
-                lastError = error;
-                // Check if this is a retryable network error
-                const isRetryableError = this.isRetryableNetworkError(error);
-                if (!isRetryableError || attempt === CONNECTION_RETRIES_LIMIT) {
-                    if (this.options.isVerbose && this.isRetryableNetworkError(error)) {
-                        console.info(colors.bgRed('Final network error after retries'), `Attempt ${attempt}/${CONNECTION_RETRIES_LIMIT}:`, error);
-                    }
-                    throw error;
-                }
-                // Calculate exponential backoff delay
-                const baseDelay = 1000; // 1 second
-                const backoffDelay = baseDelay * Math.pow(2, attempt - 1);
-                const jitterDelay = Math.random() * 500; // Add some randomness
-                const totalDelay = backoffDelay + jitterDelay;
-                if (this.options.isVerbose) {
-                    console.info(colors.bgYellow('Retrying network request'), `Attempt ${attempt}/${CONNECTION_RETRIES_LIMIT}, waiting ${Math.round(totalDelay)}ms:`, error.message);
-                }
-                // Wait before retrying
-                await new Promise((resolve) => setTimeout(resolve, totalDelay));
-            }
-        }
-        throw lastError;
+    async callChatModel(prompt) {
+        return this.callChatModelStream(prompt, () => { });
+    }
+    /**
+     * Calls OpenAI compatible API to use a chat model with streaming.
+     */
+    async callChatModelStream(prompt, onProgress, _options) {
+        return callOpenAiCompatibleChatModel({
+            prompt,
+            onProgress,
+            title: this.title,
+            executionToolsOptions: this.options,
+            getClient: () => this.getClient(),
+            executeRateLimitedRequest: (requestFn) => this.executeRateLimitedRequest(requestFn),
+            computeUsage: (...usageArguments) => this.computeUsage(...usageArguments),
+            getDefaultChatModel: () => this.getDefaultChatModel(),
+        });
     }
     /**
-     * Determines if an error is retryable (network-related errors)
+     * Executes one OpenAI request under the shared rate limiter and network retry policy.
      */
-    isRetryableNetworkError(error) {
-        const errorMessage = error.message.toLowerCase();
-        const errorCode = error.code;
-        // Network connection errors that should be retried
-        const retryableErrors = [
-            'econnreset',
-            'enotfound',
-            'econnrefused',
-            'etimedout',
-            'socket hang up',
-            'network error',
-            'fetch failed',
-            'connection reset',
-            'connection refused',
-            'timeout',
-        ];
-        // Check error message
-        if (retryableErrors.some((retryableError) => errorMessage.includes(retryableError))) {
-            return true;
-        }
-        // Check error code
-        if (errorCode && retryableErrors.includes(errorCode.toLowerCase())) {
-            return true;
-        }
-        // Check for specific HTTP status codes that are retryable
-        const errorWithStatus = error;
-        const httpStatus = errorWithStatus.status || errorWithStatus.statusCode;
-        if (httpStatus && [429, 500, 502, 503, 504].includes(httpStatus)) {
-            return true;
-        }
-        return false;
+    async executeRateLimitedRequest(requestFn) {
+        return this.requestManager.executeRateLimitedRequest(requestFn);
+    }
+    /**
+     * Calls OpenAI API to use a complete model.
+     */
+    async callCompletionModel(prompt) {
+        return this.nonChatPromptCaller.callCompletionModel(prompt);
+    }
+    /**
+     * Calls OpenAI compatible API to use a embedding model
+     */
+    async callEmbeddingModel(prompt) {
+        return this.nonChatPromptCaller.callEmbeddingModel(prompt);
+    }
+    /**
+     * Calls OpenAI compatible API to use a image generation model
+     */
+    async callImageGenerationModel(prompt) {
+        return this.nonChatPromptCaller.callImageGenerationModel(prompt);
+    }
+    // <- Note: [🤖] callXxxModel
+    /**
+     * Get the model that should be used as default
+     */
+    getDefaultModel(defaultModelName) {
+        return this.modelCatalog.getDefaultModel(defaultModelName);
     }
 }
 // TODO: [🛄] Some way how to re-wrap the errors from `OpenAiCompatibleExecutionTools`