@promptbook/openai 0.111.0-7 → 0.112.0-12

package/esm/index.es.js

@@ -23,7 +23,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.111.0-7';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-12';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -775,16 +775,14 @@ class Color {
     }
     toHex() {
         if (this.alpha === 255) {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
                 .toString(16)
-                .padStart(2, '0')}${this.blue.toString(16).padStart(2, '0')}`;
+                .padStart(2, '0')}`;
         }
         else {
-            return `#${this.red.toString(16).padStart(2, '0')}${this.green
-                .toString(16)
-                .padStart(2, '0')}${this.blue.toString(16).padStart(2, '0')}${this.alpha
+            return `#${this.red.toString(16).padStart(2, '0')}${this.green.toString(16).padStart(2, '0')}${this.blue
                 .toString(16)
-                .padStart(2, '0')}`;
+                .padStart(2, '0')}${this.alpha.toString(16).padStart(2, '0')}`;
         }
     }
     toRgb() {
@@ -994,6 +992,9 @@ const PROMPTBOOK_COLOR = Color.fromString('promptbook');
     LINE: Color.fromHex('#eeeeee'),
     SEPARATOR: Color.fromHex('#cccccc'),
     COMMITMENT: Color.fromHex('#DA0F78'),
+    NOTE_COMMITMENT: Color.fromHex('#8080807e'),
+    TODO_COMMITMENT_TEXT: Color.fromHex('#000000'),
+    TODO_COMMITMENT_BACKGROUND: Color.fromHex('#FFEB3B'),
     PARAMETER: Color.fromHex('#8e44ad'),
     CODE_BLOCK: Color.fromHex('#7700ffff'),
 });
@@ -1844,6 +1845,19 @@ class CollectionError extends Error {
     }
 }
 
+/**
+ * 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
  *
@@ -2099,6 +2113,7 @@ const PROMPTBOOK_ERRORS = {
     WrappedError,
     NotAllowed,
     DatabaseError,
+    ConflictError,
     // TODO: [🪑]> VersionMismatchError,
 };
 /**
@@ -2581,6 +2596,107 @@ function normalizeTo_snake_case(text) {
     return normalizeTo_SCREAMING_CASE(text).toLowerCase();
 }
 
+/**
+ * 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 registerToolCallProgressListener(listener) {
+    toolCallProgressListenerCounter += 1;
+    const token = `tool-progress:${Date.now()}:${toolCallProgressListenerCounter}`;
+    toolCallProgressListeners.set(token, listener);
+    return token;
+}
+/**
+ * Unregisters one in-memory progress listener.
+ *
+ * @param token - Token previously created by `registerToolCallProgressListener`.
+ * @private internal runtime wiring for commitment tools
+ */
+function unregisterToolCallProgressListener(token) {
+    toolCallProgressListeners.delete(token);
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */
+
+/**
+ * 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
+ */
+
 /**
  * Represents the uncertain value
  *
@@ -2600,6 +2716,7 @@ const UNCERTAIN_ZERO_VALUE = $deepFreeze({ value: 0, isUncertain: true });
  */
 const ZERO_USAGE = $deepFreeze({
     price: ZERO_VALUE,
+    duration: ZERO_VALUE,
     input: {
         tokensCount: ZERO_VALUE,
         charactersCount: ZERO_VALUE,
@@ -2626,6 +2743,7 @@ const ZERO_USAGE = $deepFreeze({
  */
 const UNCERTAIN_USAGE = $deepFreeze({
     price: UNCERTAIN_ZERO_VALUE,
+    duration: UNCERTAIN_ZERO_VALUE,
     input: {
         tokensCount: UNCERTAIN_ZERO_VALUE,
         charactersCount: UNCERTAIN_ZERO_VALUE,
@@ -2649,6 +2767,24 @@ const UNCERTAIN_USAGE = $deepFreeze({
  * Note: [💞] Ignore a discrepancy between file name and entity name
  */
 
+/**
+ * Make UncertainNumber
+ *
+ * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
+ * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
+ *
+ * @private utility for initializating UncertainNumber
+ */
+function uncertainNumber(value, isUncertain) {
+    if (value === null || value === undefined || Number.isNaN(value)) {
+        return UNCERTAIN_ZERO_VALUE;
+    }
+    if (isUncertain === true) {
+        return { value, isUncertain };
+    }
+    return { value };
+}
+
 /**
  * Helper of usage compute
  *
@@ -2668,24 +2804,6 @@ function computeUsageCounts(content) {
     };
 }
 
-/**
- * Make UncertainNumber
- *
- * @param value value of the uncertain number, if `NaN` or `undefined`, it will be set to 0 and `isUncertain=true`
- * @param isUncertain if `true`, the value is uncertain, otherwise depends on the value
- *
- * @private utility for initializating UncertainNumber
- */
-function uncertainNumber(value, isUncertain) {
-    if (value === null || value === undefined || Number.isNaN(value)) {
-        return UNCERTAIN_ZERO_VALUE;
-    }
-    if (isUncertain === true) {
-        return { value, isUncertain };
-    }
-    return { value };
-}
-
 /**
  * Create price per one token based on the string value found on openai page
  *
@@ -3377,11 +3495,12 @@ const OPENAI_MODELS = exportJson({
  * @param promptContent The content of the prompt
  * @param resultContent The content of the result (for embedding prompts or failed prompts pass empty string)
  * @param rawResponse The raw response from OpenAI API
+ * @param duration The duration of the execution
  * @throws {PipelineExecutionError} If the usage is not defined in the response from OpenAI
  * @private internal utility of `OpenAiExecutionTools`
  */
 function computeOpenAiUsage(promptContent, // <- Note: Intentionally using [] to access type properties to bring jsdoc from Prompt/PromptResult to consumer
-resultContent, rawResponse) {
+resultContent, rawResponse, duration = ZERO_VALUE) {
     var _a, _b;
     if (rawResponse.usage === undefined) {
         throw new PipelineExecutionError('The usage is not defined in the response from OpenAI');
@@ -3409,6 +3528,7 @@ resultContent, rawResponse) {
     }
     return {
         price,
+        duration,
         input: {
             tokensCount: uncertainNumber(rawResponse.usage.prompt_tokens),
             ...computeUsageCounts(promptContent),
@@ -3432,8 +3552,15 @@ resultContent, rawResponse) {
  */
 function addUsage(...usageItems) {
     return usageItems.reduce((acc, item) => {
-        var _a;
+        var _a, _b, _c, _d;
         acc.price.value += ((_a = item.price) === null || _a === void 0 ? void 0 : _a.value) || 0;
+        if ((_b = item.price) === null || _b === void 0 ? void 0 : _b.isUncertain) {
+            acc.price.isUncertain = true;
+        }
+        acc.duration.value += ((_c = item.duration) === null || _c === void 0 ? void 0 : _c.value) || 0;
+        if ((_d = item.duration) === null || _d === void 0 ? void 0 : _d.isUncertain) {
+            acc.duration.isUncertain = true;
+        }
         for (const key of Object.keys(acc.input)) {
             // eslint-disable-next-line @typescript-eslint/ban-ts-comment
             //@ts-ignore
@@ -3486,22 +3613,6 @@ function mapToolsToOpenAi(tools) {
     }));
 }
 
-/**
- * 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';
-/**
- * Note: [💞] Ignore a discrepancy between file name and entity name
- */
-
 /**
  * Builds a tool invocation script that injects hidden runtime context into tool args.
  *
@@ -3520,6 +3631,15 @@ function buildToolInvocationScript(options) {
             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);
     `;
 }
@@ -3606,6 +3726,42 @@ function clonePromptPreservingFiles(prompt) {
     }
     return clonedPrompt;
 }
+/**
+ * Creates one structured log entry for streamed tool-call updates.
+ */
+function createToolCallLogEntry$2(options) {
+    return {
+        createdAt: $getCurrentDate(),
+        kind: options.kind,
+        level: options.level,
+        title: options.title,
+        message: options.message,
+        payload: options.payload,
+    };
+}
+/**
+ * Appends one incremental progress update to the currently tracked tool-call snapshot.
+ */
+function applyToolCallProgressUpdate$2(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,
+    };
+}
+/**
+ * Resolves the final lifecycle state for one tool call after execution ends.
+ */
+function resolveFinalToolCallState$2(options) {
+    if (options.errors && options.errors.length > 0) {
+        return 'ERROR';
+    }
+    if (options.currentState === 'ERROR') {
+        return 'ERROR';
+    }
+    return 'COMPLETE';
+}
 /**
  * Execution Tools for calling OpenAI API or other OpenAI compatible provider
  *
@@ -3688,17 +3844,17 @@ class OpenAiCompatibleExecutionTools {
     /**
      * Calls OpenAI compatible API to use a chat model with streaming.
      */
-    async callChatModelStream(prompt, onProgress) {
+    async callChatModelStream(prompt, onProgress, options) {
         // Deep clone prompt and modelRequirements to avoid mutation across calls
         const clonedPrompt = clonePromptPreservingFiles(prompt);
         // Use local Set for retried parameters to ensure independence and thread safety
         const retriedUnsupportedParameters = new Set();
-        return this.callChatModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, [], retriedUnsupportedParameters, onProgress);
+        return this.callChatModelWithRetry(clonedPrompt, clonedPrompt.modelRequirements, [], retriedUnsupportedParameters, onProgress, options);
     }
     /**
      * Internal method that handles parameter retry for chat model calls
      */
-    async callChatModelWithRetry(prompt, currentModelRequirements, attemptStack = [], retriedUnsupportedParameters = new Set(), onProgress) {
+    async callChatModelWithRetry(prompt, currentModelRequirements, attemptStack = [], retriedUnsupportedParameters = new Set(), onProgress, options) {
         var _a;
         if (this.options.isVerbose) {
             console.info(`💬 ${this.title} callChatModel call`, { prompt, currentModelRequirements });
@@ -3777,6 +3933,7 @@ class OpenAiCompatibleExecutionTools {
         }
         let totalUsage = {
             price: uncertainNumber(0),
+            duration: uncertainNumber(0),
             input: {
                 tokensCount: uncertainNumber(0),
                 charactersCount: uncertainNumber(0),
@@ -3811,6 +3968,7 @@ class OpenAiCompatibleExecutionTools {
                 console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
             }
             try {
+                const turnStart = $getCurrentDate();
                 const rawResponse = await this.limiter
                     .schedule(() => this.makeRequestWithNetworkRetry(() => client.chat.completions.create(rawRequest)))
                     .catch((error) => {
@@ -3820,6 +3978,7 @@ class OpenAiCompatibleExecutionTools {
                     }
                     throw error;
                 });
+                const turnComplete = $getCurrentDate();
                 if (this.options.isVerbose) {
                     console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
                 }
@@ -3828,7 +3987,8 @@ class OpenAiCompatibleExecutionTools {
                 }
                 const responseMessage = rawResponse.choices[0].message;
                 messages.push(responseMessage);
-                const usage = this.computeUsage(content || '', responseMessage.content || '', rawResponse);
+                const duration = uncertainNumber((new Date(turnComplete).getTime() - new Date(turnStart).getTime()) / 1000);
+                const usage = this.computeUsage(content || '', responseMessage.content || '', rawResponse, duration);
                 totalUsage = addUsage(totalUsage, usage);
                 if (responseMessage.tool_calls && responseMessage.tool_calls.length > 0) {
                     const toolCallStartedAt = new Map();
@@ -3836,7 +3996,7 @@ class OpenAiCompatibleExecutionTools {
                         onProgress({
                             content: responseMessage.content || '',
                             modelName: rawResponse.model || modelName,
-                            timing: { start, complete: $getCurrentDate() },
+                            timing: { start, complete: turnComplete },
                             usage: totalUsage,
                             toolCalls: responseMessage.tool_calls.map((toolCall) => {
                                 const calledAt = $getCurrentDate();
@@ -3849,6 +4009,17 @@ class OpenAiCompatibleExecutionTools {
                                     result: '',
                                     rawToolCall: toolCall,
                                     createdAt: calledAt,
+                                    state: 'PENDING',
+                                    logs: [
+                                        createToolCallLogEntry$2({
+                                            kind: 'request',
+                                            title: 'Request prepared',
+                                            message: `Prepared ${String(toolCall.function.name)} request.`,
+                                            payload: {
+                                                arguments: toolCall.function.arguments,
+                                            },
+                                        }),
+                                    ],
                                 };
                             }),
                             rawPromptContent,
@@ -3862,6 +4033,24 @@ class OpenAiCompatibleExecutionTools {
                         const calledAt = toolCall.id
                             ? toolCallStartedAt.get(toolCall.id) || $getCurrentDate()
                             : $getCurrentDate();
+                        let currentToolCallSnapshot = {
+                            name: functionName,
+                            arguments: functionArgs,
+                            result: '',
+                            rawToolCall: toolCall,
+                            createdAt: calledAt,
+                            state: 'PENDING',
+                            logs: [
+                                createToolCallLogEntry$2({
+                                    kind: 'request',
+                                    title: 'Request prepared',
+                                    message: `Prepared ${functionName} request.`,
+                                    payload: {
+                                        arguments: functionArgs,
+                                    },
+                                }),
+                            ],
+                        };
                         const executionTools = this.options
                             .executionTools;
                         if (!executionTools || !executionTools.script) {
@@ -3872,36 +4061,98 @@ class OpenAiCompatibleExecutionTools {
                             ? executionTools.script
                             : [executionTools.script];
                         let functionResponse;
+                        let assistantVisibleFunctionResponse;
+                        let toolResult;
                         let errors;
                         try {
                             const scriptTool = scriptTools[0]; // <- TODO: [🧠] Which script tool to use?
-                            functionResponse = await scriptTool.execute({
-                                scriptLanguage: 'javascript',
-                                script: buildToolInvocationScript({
-                                    functionName,
-                                    functionArgsExpression: functionArgs,
-                                }),
-                                parameters: prompt.parameters,
+                            const progressListenerToken = registerToolCallProgressListener((update) => {
+                                currentToolCallSnapshot = applyToolCallProgressUpdate$2(currentToolCallSnapshot, update);
+                                if (!onProgress) {
+                                    return;
+                                }
+                                onProgress({
+                                    content: responseMessage.content || '',
+                                    modelName: rawResponse.model || modelName,
+                                    timing: { start, complete: $getCurrentDate() },
+                                    usage: totalUsage,
+                                    toolCalls: [currentToolCallSnapshot],
+                                    rawPromptContent,
+                                    rawRequest,
+                                    rawResponse,
+                                });
                             });
+                            try {
+                                functionResponse = await scriptTool.execute({
+                                    scriptLanguage: 'javascript',
+                                    script: buildToolInvocationScript({
+                                        functionName,
+                                        functionArgsExpression: functionArgs,
+                                    }),
+                                    parameters: {
+                                        ...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)];
                         }
                         messages.push({
                             role: 'tool',
                             tool_call_id: toolCall.id,
-                            content: functionResponse,
+                            content: assistantVisibleFunctionResponse,
                         });
-                        toolCalls.push({
-                            name: functionName,
-                            arguments: functionArgs,
-                            result: functionResponse,
+                        const completedToolCall = {
+                            ...currentToolCallSnapshot,
+                            result: toolResult,
                             rawToolCall: toolCall,
                             createdAt: calledAt,
                             errors,
-                        });
+                            state: resolveFinalToolCallState$2({
+                                currentState: currentToolCallSnapshot.state,
+                                errors,
+                            }),
+                            logs: [
+                                ...(currentToolCallSnapshot.logs || []),
+                                createToolCallLogEntry$2({
+                                    kind: errors && errors.length > 0 ? 'error' : 'result',
+                                    level: errors && errors.length > 0 ? 'error' : 'info',
+                                    title: errors && errors.length > 0 ? 'Execution failed' : 'Execution finished',
+                                    message: errors && errors.length > 0
+                                        ? `${functionName} failed before returning a final result.`
+                                        : `${functionName} returned a result.`,
+                                }),
+                            ],
+                        };
+                        toolCalls.push(completedToolCall);
+                        if (onProgress) {
+                            onProgress({
+                                content: responseMessage.content || '',
+                                modelName: rawResponse.model || modelName,
+                                timing: { start, complete: $getCurrentDate() },
+                                usage: totalUsage,
+                                toolCalls: [completedToolCall],
+                                rawPromptContent,
+                                rawRequest,
+                                rawResponse,
+                            });
+                        }
                     });
                     continue;
                 }
@@ -3990,7 +4241,7 @@ class OpenAiCompatibleExecutionTools {
                 });
                 // Remove the unsupported parameter and retry
                 const modifiedModelRequirements = removeUnsupportedModelRequirement(currentModelRequirements, unsupportedParameter);
-                return this.callChatModelWithRetry(prompt, modifiedModelRequirements, attemptStack, retriedUnsupportedParameters, onProgress);
+                return this.callChatModelWithRetry(prompt, modifiedModelRequirements, attemptStack, retriedUnsupportedParameters, onProgress, options);
             }
         }
         throw new PipelineExecutionError(`Tool calling loop did not return a result from ${this.title}`);
@@ -4036,6 +4287,7 @@ class OpenAiCompatibleExecutionTools {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
         try {
+            const turnStart = $getCurrentDate();
             const rawResponse = await this.limiter
                 .schedule(() => this.makeRequestWithNetworkRetry(() => client.completions.create(rawRequest)))
                 .catch((error) => {
@@ -4045,10 +4297,10 @@ class OpenAiCompatibleExecutionTools {
                 }
                 throw error;
             });
+            const turnComplete = $getCurrentDate();
             if (this.options.isVerbose) {
                 console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
-            const complete = $getCurrentDate();
             if (!rawResponse.choices[0]) {
                 throw new PipelineExecutionError(`No choises from ${this.title}`);
             }
@@ -4056,7 +4308,8 @@ class OpenAiCompatibleExecutionTools {
                 throw new PipelineExecutionError(`More than one choise from ${this.title}`);
             }
             const resultContent = rawResponse.choices[0].text;
-            const usage = this.computeUsage(content || '', resultContent || '', rawResponse);
+            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\``,
@@ -4066,7 +4319,7 @@ class OpenAiCompatibleExecutionTools {
                     modelName: rawResponse.model || modelName,
                     timing: {
                         start,
-                        complete,
+                        complete: turnComplete,
                     },
                     usage,
                     rawPromptContent,
@@ -4160,6 +4413,7 @@ class OpenAiCompatibleExecutionTools {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
         try {
+            const turnStart = $getCurrentDate();
             const rawResponse = await this.limiter
                 .schedule(() => this.makeRequestWithNetworkRetry(() => client.embeddings.create(rawRequest)))
                 .catch((error) => {
@@ -4169,15 +4423,16 @@ class OpenAiCompatibleExecutionTools {
                 }
                 throw error;
             });
+            const turnComplete = $getCurrentDate();
             if (this.options.isVerbose) {
                 console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
-            const complete = $getCurrentDate();
             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 usage = this.computeUsage(content || '', '', rawResponse);
+            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\``,
@@ -4187,7 +4442,7 @@ class OpenAiCompatibleExecutionTools {
                     modelName: rawResponse.model || modelName,
                     timing: {
                         start,
-                        complete,
+                        complete: turnComplete,
                     },
                     usage,
                     rawPromptContent,
@@ -4297,6 +4552,7 @@ class OpenAiCompatibleExecutionTools {
             console.info(colors.bgWhite('rawRequest'), JSON.stringify(rawRequest, null, 4));
         }
         try {
+            const turnStart = $getCurrentDate();
             const rawResponse = await this.limiter
                 .schedule(() => this.makeRequestWithNetworkRetry(() => client.images.generate(rawRequest)))
                 .catch((error) => {
@@ -4306,10 +4562,10 @@ class OpenAiCompatibleExecutionTools {
                 }
                 throw error;
             });
+            const turnComplete = $getCurrentDate();
             if (this.options.isVerbose) {
                 console.info(colors.bgWhite('rawResponse'), JSON.stringify(rawResponse, null, 4));
             }
-            const complete = $getCurrentDate();
             if (!rawResponse.data[0]) {
                 throw new PipelineExecutionError(`No choises from ${this.title}`);
             }
@@ -4319,6 +4575,7 @@ class OpenAiCompatibleExecutionTools {
             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\``,
@@ -4328,10 +4585,11 @@ class OpenAiCompatibleExecutionTools {
                     modelName: modelName,
                     timing: {
                         start,
-                        complete,
+                        complete: turnComplete,
                     },
                     usage: {
                         price,
+                        duration,
                         input: {
                             tokensCount: uncertainNumber(0),
                             ...computeUsageCounts(rawPromptContent),
@@ -5426,6 +5684,48 @@ async function uploadFilesToOpenAi(client, files) {
     return fileIds;
 }
 
+/**
+ * Creates one structured log entry for streamed tool-call updates.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+function createToolCallLogEntry$1(options) {
+    return {
+        createdAt: $getCurrentDate(),
+        kind: options.kind,
+        level: options.level,
+        title: options.title,
+        message: options.message,
+        payload: options.payload,
+    };
+}
+/**
+ * Appends one incremental progress update to the currently tracked tool-call snapshot.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+function applyToolCallProgressUpdate$1(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,
+    };
+}
+/**
+ * Resolves the final lifecycle state for one tool call after execution ends.
+ *
+ * @private helper of `OpenAiAssistantExecutionTools`
+ */
+function resolveFinalToolCallState$1(options) {
+    if (options.errors && options.errors.length > 0) {
+        return 'ERROR';
+    }
+    if (options.currentState === 'ERROR') {
+        return 'ERROR';
+    }
+    return 'COMPLETE';
+}
 /**
  * Execution Tools for calling OpenAI API Assistants
  *
@@ -5477,7 +5777,7 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
     /**
      * Calls OpenAI API to use a chat model with streaming.
      */
-    async callChatModelStream(prompt, onProgress) {
+    async callChatModelStream(prompt, onProgress, options) {
         var _a, _b, _c, _d, _e, _f;
         if (this.options.isVerbose) {
             console.info('💬 OpenAI callChatModel call', { prompt });
@@ -5602,6 +5902,17 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
                                         result: '',
                                         rawToolCall: toolCall,
                                         createdAt: calledAt,
+                                        state: 'PENDING',
+                                        logs: [
+                                            createToolCallLogEntry$1({
+                                                kind: 'request',
+                                                title: 'Request prepared',
+                                                message: `Prepared ${functionName} request.`,
+                                                payload: {
+                                                    arguments: toolCall.function.arguments,
+                                                },
+                                            }),
+                                        ],
                                     },
                                 ],
                             });
@@ -5619,19 +5930,67 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
                                 ? executionTools.script
                                 : [executionTools.script];
                             let functionResponse;
+                            let assistantVisibleFunctionResponse;
+                            let toolResult;
                             let errors;
+                            let currentToolCallSnapshot = {
+                                name: functionName,
+                                arguments: toolCall.function.arguments,
+                                result: '',
+                                rawToolCall: toolCall,
+                                createdAt: calledAt,
+                                state: 'PENDING',
+                                logs: [
+                                    createToolCallLogEntry$1({
+                                        kind: 'request',
+                                        title: 'Request prepared',
+                                        message: `Prepared ${functionName} request.`,
+                                        payload: {
+                                            arguments: toolCall.function.arguments,
+                                        },
+                                    }),
+                                ],
+                            };
                             try {
                                 const scriptTool = scriptTools[0]; // <- TODO: [🧠] Which script tool to use?
-                                functionResponse = await scriptTool.execute({
-                                    scriptLanguage: 'javascript',
-                                    script: buildToolInvocationScript({
-                                        functionName,
-                                        functionArgsExpression: JSON.stringify(functionArgs),
-                                    }),
-                                    parameters: prompt.parameters,
+                                const progressListenerToken = registerToolCallProgressListener((update) => {
+                                    currentToolCallSnapshot = applyToolCallProgressUpdate$1(currentToolCallSnapshot, update);
+                                    onProgress({
+                                        content: '',
+                                        modelName: 'assistant',
+                                        timing: { start, complete: $getCurrentDate() },
+                                        usage: UNCERTAIN_USAGE,
+                                        rawPromptContent,
+                                        rawRequest: null,
+                                        rawResponse: null,
+                                        toolCalls: [currentToolCallSnapshot],
+                                    });
                                 });
+                                try {
+                                    functionResponse = await scriptTool.execute({
+                                        scriptLanguage: 'javascript',
+                                        script: buildToolInvocationScript({
+                                            functionName,
+                                            functionArgsExpression: JSON.stringify(functionArgs),
+                                        }),
+                                        parameters: {
+                                            ...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;
                                 if (this.options.isVerbose) {
-                                    console.info(`✅ Tool ${functionName} executed:`, functionResponse);
+                                    console.info(`✅ Tool ${functionName} executed:`, assistantVisibleFunctionResponse);
                                 }
                             }
                             catch (error) {
@@ -5647,20 +6006,46 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
                                         \`\`\`
 
                                     `);
+                                assistantVisibleFunctionResponse = functionResponse;
+                                toolResult = functionResponse;
                                 console.error(colors.bgRed(`❌ Error executing tool ${functionName}:`));
                                 console.error(error);
                             }
                             toolOutputs.push({
                                 tool_call_id: toolCall.id,
-                                output: functionResponse,
+                                output: assistantVisibleFunctionResponse,
                             });
                             completedToolCalls.push({
-                                name: functionName,
-                                arguments: toolCall.function.arguments,
-                                result: functionResponse,
+                                ...currentToolCallSnapshot,
+                                result: toolResult,
                                 rawToolCall: toolCall,
                                 createdAt: toolCall.id ? toolCallStartedAt.get(toolCall.id) || calledAt : calledAt,
                                 errors,
+                                state: resolveFinalToolCallState$1({
+                                    currentState: currentToolCallSnapshot.state,
+                                    errors,
+                                }),
+                                logs: [
+                                    ...(currentToolCallSnapshot.logs || []),
+                                    createToolCallLogEntry$1({
+                                        kind: errors && errors.length > 0 ? 'error' : 'result',
+                                        level: errors && errors.length > 0 ? 'error' : 'info',
+                                        title: errors && errors.length > 0 ? 'Execution failed' : 'Execution finished',
+                                        message: errors && errors.length > 0
+                                            ? `${functionName} failed before returning a final result.`
+                                            : `${functionName} returned a result.`,
+                                    }),
+                                ],
+                            });
+                            onProgress({
+                                content: '',
+                                modelName: 'assistant',
+                                timing: { start, complete: $getCurrentDate() },
+                                usage: UNCERTAIN_USAGE,
+                                rawPromptContent,
+                                rawRequest: null,
+                                rawResponse: null,
+                                toolCalls: [completedToolCalls[completedToolCalls.length - 1]],
                             });
                         }
                     }
@@ -5690,8 +6075,12 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
                 throw new PipelineExecutionError('No text content in assistant response');
             }
             complete = $getCurrentDate();
+            const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
             const resultContent = textContent.text.value;
-            const usage = UNCERTAIN_USAGE;
+            const usage = {
+                ...UNCERTAIN_USAGE,
+                duration,
+            };
             // Progress callback with final result
             const finalChunk = {
                 content: resultContent,
@@ -5815,7 +6204,11 @@ class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler {
         }
         // eslint-disable-next-line prefer-const
         complete = $getCurrentDate();
-        const usage = UNCERTAIN_USAGE;
+        const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
+        const usage = {
+            ...UNCERTAIN_USAGE,
+            duration,
+        };
         // <- TODO: [🥘] Compute real usage for assistant
         //       ?> const usage = computeOpenAiUsage(content, resultContent || '', rawResponse);
         if (resultContent === null) {
@@ -6370,8 +6763,220 @@ const createOpenAiExecutionTools = Object.assign((options) => {
  * TODO: [🎶] Naming "constructor" vs "creator" vs "factory"
  */
 
-const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5.2';
+/**
+ * Fallback name used when attachment metadata does not provide any usable filename.
+ *
+ * @private function of normalizeChatAttachments
+ */
+const DEFAULT_ATTACHMENT_NAME = 'attachment';
+/**
+ * Default MIME type used when attachment metadata does not provide one.
+ *
+ * @private function of normalizeChatAttachments
+ */
+const DEFAULT_ATTACHMENT_TYPE = 'application/octet-stream';
+/**
+ * Normalizes attachment text fields to safe single-line values.
+ *
+ * @private function of normalizeChatAttachments
+ */
+function normalizeAttachmentText(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized === '' ? null : normalized;
+}
+/**
+ * Checks whether the attachment URL is an absolute HTTP(S) link.
+ *
+ * @private function of normalizeChatAttachments
+ */
+function isSupportedAttachmentUrl(value) {
+    try {
+        const parsedUrl = new URL(value);
+        return parsedUrl.protocol === 'http:' || parsedUrl.protocol === 'https:';
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Tries to infer a readable attachment name from its URL pathname.
+ *
+ * @private function of normalizeChatAttachments
+ */
+function deriveAttachmentNameFromUrl(url) {
+    try {
+        const parsedUrl = new URL(url);
+        const pathnameSegments = parsedUrl.pathname.split('/').filter(Boolean);
+        const encodedFileName = pathnameSegments[pathnameSegments.length - 1];
+        if (!encodedFileName) {
+            return DEFAULT_ATTACHMENT_NAME;
+        }
+        const decodedFileName = decodeURIComponent(encodedFileName).trim();
+        return decodedFileName === '' ? DEFAULT_ATTACHMENT_NAME : decodedFileName;
+    }
+    catch (_a) {
+        return DEFAULT_ATTACHMENT_NAME;
+    }
+}
+/**
+ * Converts unknown attachment payload into the normalized chat attachment shape.
+ *
+ * @private function of normalizeChatAttachments
+ */
+function normalizeChatAttachment(rawAttachment) {
+    if (!rawAttachment || typeof rawAttachment !== 'object' || Array.isArray(rawAttachment)) {
+        return null;
+    }
+    const rawUrl = normalizeAttachmentText(rawAttachment.url);
+    if (!rawUrl || !isSupportedAttachmentUrl(rawUrl)) {
+        return null;
+    }
+    const rawName = normalizeAttachmentText(rawAttachment.name);
+    const rawType = normalizeAttachmentText(rawAttachment.type);
+    return {
+        name: rawName || deriveAttachmentNameFromUrl(rawUrl),
+        type: rawType || DEFAULT_ATTACHMENT_TYPE,
+        url: rawUrl,
+    };
+}
+/**
+ * Normalizes a potentially invalid attachments payload from the client request.
+ *
+ * Invalid items are skipped and duplicate URLs are de-duplicated.
+ *
+ * @param {unknown} rawAttachments - The raw attachments to normalize.
+ * @returns {Array<ChatAttachment>} The normalized attachments.
+ * @public exported from `@promptbook/core`
+ */
+function normalizeChatAttachments(rawAttachments) {
+    if (!Array.isArray(rawAttachments)) {
+        return [];
+    }
+    const normalizedAttachments = [];
+    const seenUrls = new Set();
+    for (const rawAttachment of rawAttachments) {
+        const normalizedAttachment = normalizeChatAttachment(rawAttachment);
+        if (!normalizedAttachment || seenUrls.has(normalizedAttachment.url)) {
+            continue;
+        }
+        normalizedAttachments.push(normalizedAttachment);
+        seenUrls.add(normalizedAttachment.url);
+    }
+    return normalizedAttachments;
+}
+
+const DEFAULT_AGENT_KIT_MODEL_NAME = 'gpt-5-mini-2025-08-07';
+/**
+ * Creates one structured log entry for streamed tool-call updates.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function createToolCallLogEntry(options) {
+    return {
+        createdAt: $getCurrentDate(),
+        kind: options.kind,
+        level: options.level,
+        title: options.title,
+        message: options.message,
+        payload: options.payload,
+    };
+}
+/**
+ * Appends one incremental progress update to the currently tracked tool-call snapshot.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+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,
+    };
+}
+/**
+ * Resolves the final lifecycle state for one AgentKit tool call after execution ends.
+ *
+ * @private helper of `OpenAiAgentKitExecutionTools`
+ */
+function resolveFinalToolCallState(options) {
+    if (options.errors && options.errors.length > 0) {
+        return 'ERROR';
+    }
+    if (options.currentState === 'ERROR') {
+        return 'ERROR';
+    }
+    return 'COMPLETE';
+}
 const DEFAULT_JSON_SCHEMA_NAME = 'StructuredOutput';
+/**
+ * File extensions considered image inputs when MIME type is missing or generic.
+ *
+ * @private utility of Open AI
+ */
+const IMAGE_ATTACHMENT_EXTENSIONS = new Set([
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'bmp',
+    'svg',
+    'heic',
+    'heif',
+    'avif',
+    'tif',
+    'tiff',
+]);
+/**
+ * Returns one lowercase extension extracted from a filename/pathname.
+ *
+ * @private utility of Open AI
+ */
+function getLowercaseFilenameExtension(filename) {
+    const normalizedFilename = filename.trim().toLowerCase();
+    const queryStart = normalizedFilename.indexOf('?');
+    const hashStart = normalizedFilename.indexOf('#');
+    const suffixStart = queryStart === -1 && hashStart === -1
+        ? normalizedFilename.length
+        : Math.min(queryStart === -1 ? normalizedFilename.length : queryStart, hashStart === -1 ? normalizedFilename.length : hashStart);
+    const pathname = normalizedFilename.slice(0, suffixStart);
+    const lastDotIndex = pathname.lastIndexOf('.');
+    if (lastDotIndex <= 0 || lastDotIndex === pathname.length - 1) {
+        return null;
+    }
+    return pathname.slice(lastDotIndex + 1);
+}
+/**
+ * Tries to extract one extension from URL pathname.
+ *
+ * @private utility of Open AI
+ */
+function getUrlPathnameExtension(url) {
+    try {
+        const parsedUrl = new URL(url);
+        return getLowercaseFilenameExtension(decodeURIComponent(parsedUrl.pathname));
+    }
+    catch (_a) {
+        return null;
+    }
+}
+/**
+ * Checks whether one chat attachment can be sent as an image input.
+ *
+ * @private utility of Open AI
+ */
+function isImageAttachment(attachment) {
+    const normalizedType = attachment.type.trim().toLowerCase();
+    if (normalizedType.startsWith('image/')) {
+        return true;
+    }
+    const extension = getLowercaseFilenameExtension(attachment.name) || getUrlPathnameExtension(attachment.url);
+    return extension ? IMAGE_ATTACHMENT_EXTENSIONS.has(extension) : false;
+}
 /*
 TODO: Use or remove
 const EMPTY_JSON_SCHEMA: JsonSchemaDefinition['schema'] = {
@@ -6381,13 +6986,71 @@ const EMPTY_JSON_SCHEMA: JsonSchemaDefinition['schema'] = {
     additionalProperties: true,
 };
 */
+/**
+ * Determines whether a schema fragment includes meaningful constraints.
+ */
+function hasJsonSchemaContent(schema) {
+    if (!schema) {
+        return false;
+    }
+    if (typeof schema.description === 'string' && schema.description.trim() !== '') {
+        return true;
+    }
+    if (schema.additionalProperties !== undefined) {
+        return true;
+    }
+    if (schema.properties && Object.keys(schema.properties).length > 0) {
+        return true;
+    }
+    if (Array.isArray(schema.required) && schema.required.length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Normalizes inline OpenAI JSON schema payloads to the AgentKit structure.
+ */
+function normalizeJsonSchemaInput(jsonSchema) {
+    if (!jsonSchema || typeof jsonSchema !== 'object') {
+        return { schema: {}, hasSchema: false };
+    }
+    const explicitSchema = jsonSchema.schema;
+    if (explicitSchema && typeof explicitSchema === 'object') {
+        return {
+            name: jsonSchema.name,
+            strict: jsonSchema.strict,
+            schema: explicitSchema,
+            hasSchema: hasJsonSchemaContent(explicitSchema),
+        };
+    }
+    const inlineSchema = {
+        description: jsonSchema.description,
+        additionalProperties: jsonSchema.additionalProperties,
+        properties: jsonSchema.properties,
+        required: jsonSchema.required,
+    };
+    const hasInlineSchema = hasJsonSchemaContent(inlineSchema) || (typeof jsonSchema.type === 'string' && jsonSchema.type === 'object');
+    return {
+        name: jsonSchema.name,
+        strict: jsonSchema.strict,
+        schema: hasInlineSchema ? inlineSchema : {},
+        hasSchema: hasInlineSchema,
+    };
+}
+/**
+ * Builds an AgentKit-compatible JSON schema definition from the supplied payload.
+ */
 function buildJsonSchemaDefinition(jsonSchema) {
     var _a, _b, _c;
-    const schema = (_a = jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.schema) !== null && _a !== void 0 ? _a : {};
+    const normalizedSchema = normalizeJsonSchemaInput(jsonSchema);
+    const schema = (_a = normalizedSchema.schema) !== null && _a !== void 0 ? _a : {};
+    const strict = normalizedSchema.strict === undefined || normalizedSchema.strict === null
+        ? normalizedSchema.hasSchema
+        : Boolean(normalizedSchema.strict);
     return {
         type: 'json_schema',
-        name: (_b = jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.name) !== null && _b !== void 0 ? _b : DEFAULT_JSON_SCHEMA_NAME,
-        strict: Boolean(jsonSchema === null || jsonSchema === void 0 ? void 0 : jsonSchema.strict),
+        name: (_b = normalizedSchema.name) !== null && _b !== void 0 ? _b : DEFAULT_JSON_SCHEMA_NAME,
+        strict,
         schema: {
             type: 'object',
             properties: ((_c = schema.properties) !== null && _c !== void 0 ? _c : {}),
@@ -6445,6 +7108,8 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
         }
         super(options);
         this.preparedAgentKitAgent = null;
+        this.agentKitToolResultsByCallId = new Map();
+        this.agentKitToolSnapshotsByCallId = new Map();
         this.agentKitModelName = (_a = options.agentKitModelName) !== null && _a !== void 0 ? _a : DEFAULT_AGENT_KIT_MODEL_NAME;
     }
     get title() {
@@ -6462,7 +7127,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
     /**
      * Calls OpenAI AgentKit with a chat prompt (streaming).
      */
-    async callChatModelStream(prompt, onProgress) {
+    async callChatModelStream(prompt, onProgress, options) {
         const { content, parameters, modelRequirements } = prompt;
         if (modelRequirements.modelVariant !== 'CHAT') {
             throw new PipelineExecutionError('Use callChatModel only for CHAT variant');
@@ -6489,6 +7154,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
             rawPromptContent,
             onProgress,
             responseFormatOutputType,
+            signal: options === null || options === void 0 ? void 0 : options.signal,
         });
     }
     /**
@@ -6602,12 +7268,13 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                         : undefined,
                     strict: false,
                     execute: async (input, runContext, details) => {
-                        var _a, _b, _c;
+                        var _a, _b, _c, _d;
                         const scriptTool = scriptTools[0];
                         const functionName = toolDefinition.name;
                         const calledAt = $getCurrentDate();
                         const callId = (_a = details === null || details === void 0 ? void 0 : details.toolCall) === null || _a === void 0 ? void 0 : _a.callId;
                         const functionArgs = input !== null && input !== void 0 ? input : {};
+                        const executionContext = (_b = runContext === null || runContext === void 0 ? void 0 : runContext.context) !== null && _b !== void 0 ? _b : undefined;
                         if (this.options.isVerbose) {
                             console.info('[🤰]', 'Executing AgentKit tool', {
                                 functionName,
@@ -6616,18 +7283,86 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                             });
                         }
                         try {
-                            return await scriptTool.execute({
-                                scriptLanguage: 'javascript',
-                                script: buildToolInvocationScript({
-                                    functionName,
-                                    functionArgsExpression: JSON.stringify(functionArgs),
-                                }),
-                                parameters: (_c = (_b = runContext === null || runContext === void 0 ? void 0 : runContext.context) === null || _b === void 0 ? void 0 : _b.parameters) !== null && _c !== void 0 ? _c : {},
+                            let currentToolCallSnapshot = {
+                                name: functionName,
+                                arguments: functionArgs,
+                                result: '',
+                                rawToolCall: details === null || details === void 0 ? void 0 : details.toolCall,
+                                createdAt: calledAt,
+                                state: 'PENDING',
+                                logs: [
+                                    createToolCallLogEntry({
+                                        kind: 'request',
+                                        title: 'Request prepared',
+                                        message: `Prepared ${functionName} request.`,
+                                        payload: {
+                                            arguments: functionArgs,
+                                        },
+                                    }),
+                                ],
+                            };
+                            const progressListenerToken = registerToolCallProgressListener((update) => {
+                                currentToolCallSnapshot = applyToolCallProgressUpdate(currentToolCallSnapshot, update);
+                                if (callId) {
+                                    this.agentKitToolSnapshotsByCallId.set(callId, currentToolCallSnapshot);
+                                }
+                                if (!(executionContext === null || executionContext === void 0 ? void 0 : executionContext.onToolProgress)) {
+                                    return;
+                                }
+                                executionContext.onToolProgress({
+                                    content: '',
+                                    modelName: executionContext.modelName || this.agentKitModelName,
+                                    timing: {
+                                        start: executionContext.startedAt || calledAt,
+                                        complete: $getCurrentDate(),
+                                    },
+                                    usage: UNCERTAIN_USAGE,
+                                    rawPromptContent: (executionContext.rawPromptContent || ''),
+                                    rawRequest: null,
+                                    rawResponse: {},
+                                    toolCalls: [currentToolCallSnapshot],
+                                });
                             });
+                            let functionResponse;
+                            try {
+                                functionResponse = await scriptTool.execute({
+                                    scriptLanguage: 'javascript',
+                                    script: buildToolInvocationScript({
+                                        functionName,
+                                        functionArgsExpression: JSON.stringify(functionArgs),
+                                    }),
+                                    parameters: {
+                                        ...((_c = executionContext === null || executionContext === void 0 ? void 0 : executionContext.parameters) !== null && _c !== void 0 ? _c : {}),
+                                        [TOOL_PROGRESS_TOKEN_PARAMETER]: progressListenerToken,
+                                    },
+                                });
+                            }
+                            finally {
+                                unregisterToolCallProgressListener(progressListenerToken);
+                            }
+                            return this.resolveAgentKitToolResponse(callId, functionResponse);
                         }
                         catch (error) {
                             assertsError(error);
                             const serializedError = serializeError(error);
+                            const failedToolCall = {
+                                name: functionName,
+                                arguments: functionArgs,
+                                result: '',
+                                rawToolCall: details === null || details === void 0 ? void 0 : details.toolCall,
+                                createdAt: calledAt,
+                                state: 'ERROR',
+                                errors: [serializedError],
+                                logs: [
+                                    createToolCallLogEntry({
+                                        kind: 'error',
+                                        level: 'error',
+                                        title: 'Execution failed',
+                                        message: `${functionName} failed before returning a result.`,
+                                        payload: serializedError,
+                                    }),
+                                ],
+                            };
                             const errorMessage = spaceTrim$2((block) => `
 
                                         The invoked tool \`${functionName}\` failed with error:
@@ -6642,6 +7377,22 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                                 callId,
                                 error: serializedError,
                             });
+                            if (callId) {
+                                this.agentKitToolSnapshotsByCallId.set(callId, failedToolCall);
+                            }
+                            (_d = executionContext === null || executionContext === void 0 ? void 0 : executionContext.onToolProgress) === null || _d === void 0 ? void 0 : _d.call(executionContext, {
+                                content: '',
+                                modelName: executionContext.modelName || this.agentKitModelName,
+                                timing: {
+                                    start: executionContext.startedAt || calledAt,
+                                    complete: $getCurrentDate(),
+                                },
+                                usage: UNCERTAIN_USAGE,
+                                rawPromptContent: (executionContext.rawPromptContent || ''),
+                                rawRequest: null,
+                                rawResponse: {},
+                                toolCalls: [failedToolCall],
+                            });
                             return errorMessage;
                         }
                     },
@@ -6664,7 +7415,7 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Runs a prepared AgentKit agent and streams results back to the caller.
      */
     async callChatModelStreamWithPreparedAgent(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f;
         const { openAiAgentKitAgent, prompt, onProgress } = options;
         const rawPromptContent = (_a = options.rawPromptContent) !== null && _a !== void 0 ? _a : templateParameters(prompt.content, {
             ...prompt.parameters,
@@ -6679,6 +7430,8 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
         let latestContent = '';
         const toolCalls = [];
         const toolCallIndexById = new Map();
+        this.agentKitToolResultsByCallId.clear();
+        this.agentKitToolSnapshotsByCallId.clear();
         const inputItems = await this.buildAgentKitInputItems(prompt, rawPromptContent);
         const rawRequest = {
             agentName: agentForRun.name,
@@ -6686,8 +7439,35 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
         };
         const streamResult = await run(agentForRun, inputItems, {
             stream: true,
-            context: { parameters: prompt.parameters },
+            context: {
+                parameters: prompt.parameters,
+                onToolProgress: onProgress,
+                rawPromptContent,
+                startedAt: start,
+                modelName: this.agentKitModelName,
+            },
+            signal: options.signal,
         });
+        /**
+         * Emits one explicit terminal stream snapshot as soon as the visible model output stream ends.
+         *
+         * This intentionally happens before `streamResult.completed` resolves because the SDK can keep
+         * post-stream bookkeeping alive after the last user-visible token has already been delivered.
+         */
+        const emitFinishedStreamSnapshot = () => {
+            var _a;
+            onProgress({
+                content: ((_a = streamResult.finalOutput) !== null && _a !== void 0 ? _a : latestContent),
+                modelName: this.agentKitModelName,
+                timing: { start, complete: $getCurrentDate() },
+                usage: UNCERTAIN_USAGE,
+                rawPromptContent: rawPromptContent,
+                rawRequest: null,
+                rawResponse: { runResult: streamResult },
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                isFinished: true,
+            });
+        };
         for await (const event of streamResult) {
             if (event.type === 'raw_model_stream_event' && ((_b = event.data) === null || _b === void 0 ? void 0 : _b.type) === 'output_text_delta') {
                 latestContent += event.data.delta;
@@ -6710,9 +7490,21 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                         arguments: rawItem.arguments,
                         rawToolCall: rawItem,
                         createdAt: $getCurrentDate(),
+                        state: 'PENDING',
+                        logs: [
+                            createToolCallLogEntry({
+                                kind: 'request',
+                                title: 'Request prepared',
+                                message: `Prepared ${String(rawItem.name)} request.`,
+                                payload: {
+                                    arguments: rawItem.arguments,
+                                },
+                            }),
+                        ],
                     };
                     toolCallIndexById.set(rawItem.callId, toolCalls.length);
                     toolCalls.push(toolCall);
+                    this.agentKitToolSnapshotsByCallId.set(rawItem.callId, toolCall);
                     onProgress({
                         content: latestContent,
                         modelName: this.agentKitModelName,
@@ -6726,15 +7518,34 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 }
                 if (event.name === 'tool_output' && (rawItem === null || rawItem === void 0 ? void 0 : rawItem.type) === 'function_call_result') {
                     const index = toolCallIndexById.get(rawItem.callId);
-                    const result = this.formatAgentKitToolOutput(rawItem.output);
+                    const result = this.resolveAgentKitToolOutputResult(rawItem.callId, rawItem.output);
+                    const progressToolCall = rawItem.callId
+                        ? this.agentKitToolSnapshotsByCallId.get(rawItem.callId)
+                        : undefined;
                     if (index !== undefined) {
                         const existingToolCall = toolCalls[index];
                         const completedToolCall = {
                             ...existingToolCall,
+                            ...(progressToolCall || {}),
                             result,
                             rawToolCall: rawItem,
+                            state: resolveFinalToolCallState({
+                                currentState: (_d = progressToolCall === null || progressToolCall === void 0 ? void 0 : progressToolCall.state) !== null && _d !== void 0 ? _d : existingToolCall.state,
+                                errors: (_e = progressToolCall === null || progressToolCall === void 0 ? void 0 : progressToolCall.errors) !== null && _e !== void 0 ? _e : existingToolCall.errors,
+                            }),
+                            logs: [
+                                ...((progressToolCall === null || progressToolCall === void 0 ? void 0 : progressToolCall.logs) ||
+                                    existingToolCall.logs ||
+                                    []),
+                                createToolCallLogEntry({
+                                    kind: 'result',
+                                    title: 'Execution finished',
+                                    message: `${existingToolCall.name} returned a result.`,
+                                }),
+                            ],
                         };
                         toolCalls[index] = completedToolCall;
+                        this.agentKitToolSnapshotsByCallId.delete(rawItem.callId);
                         onProgress({
                             content: latestContent,
                             modelName: this.agentKitModelName,
@@ -6749,14 +7560,19 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                 }
             }
         }
+        emitFinishedStreamSnapshot();
         await streamResult.completed;
         const complete = $getCurrentDate();
-        const finalContent = ((_d = streamResult.finalOutput) !== null && _d !== void 0 ? _d : latestContent);
+        const duration = uncertainNumber((new Date(complete).getTime() - new Date(start).getTime()) / 1000);
+        const finalContent = ((_f = streamResult.finalOutput) !== null && _f !== void 0 ? _f : latestContent);
         const finalResult = {
             content: finalContent,
             modelName: this.agentKitModelName,
             timing: { start, complete },
-            usage: UNCERTAIN_USAGE,
+            usage: {
+                ...UNCERTAIN_USAGE,
+                duration,
+            },
             rawPromptContent: rawPromptContent,
             rawRequest,
             rawResponse: { runResult: streamResult },
@@ -6783,9 +7599,13 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
                     });
                 }
                 else {
+                    const userThreadContent = await this.buildAgentKitUserContentWithAttachments({
+                        textContent: typeof content === 'string' ? content : String(content !== null && content !== void 0 ? content : ''),
+                        rawAttachments: message.attachments,
+                    });
                     inputItems.push({
                         role: 'user',
-                        content,
+                        content: userThreadContent,
                     });
                 }
             }
@@ -6801,18 +7621,64 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
      * Builds the user message content for AgentKit runs, including file inputs when provided.
      */
     async buildAgentKitUserContent(prompt, rawPromptContent) {
-        if ('files' in prompt && Array.isArray(prompt.files) && prompt.files.length > 0) {
-            const fileItems = await Promise.all(prompt.files.map(async (file) => {
-                const arrayBuffer = await file.arrayBuffer();
-                const base64 = Buffer.from(arrayBuffer).toString('base64');
-                return {
-                    type: 'input_image',
-                    image: `data:${file.type};base64,${base64}`,
-                };
-            }));
-            return [{ type: 'input_text', text: rawPromptContent }, ...fileItems];
+        const files = 'files' in prompt && Array.isArray(prompt.files) ? prompt.files : undefined;
+        const rawAttachments = 'attachments' in prompt ? prompt.attachments : undefined;
+        return this.buildAgentKitUserContentWithAttachments({
+            textContent: rawPromptContent,
+            rawAttachments,
+            files,
+        });
+    }
+    /**
+     * Converts uploaded `File` objects into AgentKit `input_image` entries.
+     */
+    async createAgentKitInputImageItemsFromFiles(files) {
+        return Promise.all(files.map(async (file) => {
+            const arrayBuffer = await file.arrayBuffer();
+            const base64 = Buffer.from(arrayBuffer).toString('base64');
+            return {
+                type: 'input_image',
+                image: `data:${file.type};base64,${base64}`,
+            };
+        }));
+    }
+    /**
+     * Converts image chat attachments into AgentKit `input_image` entries.
+     *
+     * Note: This keeps images in the same completion request as multimodal input.
+     */
+    createAgentKitInputImageItemsFromAttachments(rawAttachments) {
+        return normalizeChatAttachments(rawAttachments)
+            .filter((attachment) => isImageAttachment(attachment))
+            .map((attachment) => ({
+            type: 'input_image',
+            image: attachment.url,
+        }));
+    }
+    /**
+     * Builds AgentKit user content that can include text, uploaded files, and image attachments.
+     */
+    async buildAgentKitUserContentWithAttachments(options) {
+        var _a;
+        const { textContent, rawAttachments, files } = options;
+        const contentItems = [];
+        if (textContent.trim() !== '') {
+            contentItems.push({
+                type: 'input_text',
+                text: textContent,
+            });
         }
-        return rawPromptContent;
+        contentItems.push(...this.createAgentKitInputImageItemsFromAttachments(rawAttachments));
+        if (files && files.length > 0) {
+            contentItems.push(...(await this.createAgentKitInputImageItemsFromFiles(files)));
+        }
+        if (contentItems.length === 0) {
+            return textContent;
+        }
+        if (contentItems.length === 1 && ((_a = contentItems[0]) === null || _a === void 0 ? void 0 : _a.type) === 'input_text') {
+            return textContent;
+        }
+        return contentItems;
     }
     /**
      * Normalizes AgentKit tool outputs into a string for Promptbook tool call results.
@@ -6829,6 +7695,32 @@ class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler {
         }
         return JSON.stringify(output !== null && output !== void 0 ? output : null);
     }
+    /**
+     * Resolves the assistant-visible AgentKit tool response while preserving structured tool result data.
+     */
+    resolveAgentKitToolResponse(callId, functionResponse) {
+        const toolExecutionEnvelope = parseToolExecutionEnvelope(functionResponse);
+        if (!toolExecutionEnvelope) {
+            return functionResponse;
+        }
+        if (callId) {
+            this.agentKitToolResultsByCallId.set(callId, toolExecutionEnvelope.toolResult);
+        }
+        return toolExecutionEnvelope.assistantMessage;
+    }
+    /**
+     * Resolves the stored Promptbook tool result for one AgentKit tool call.
+     */
+    resolveAgentKitToolOutputResult(callId, output) {
+        if (callId) {
+            const storedToolResult = this.agentKitToolResultsByCallId.get(callId);
+            if (storedToolResult !== undefined) {
+                this.agentKitToolResultsByCallId.delete(callId);
+                return storedToolResult;
+            }
+        }
+        return this.formatAgentKitToolOutput(output);
+    }
     /**
      * Returns AgentKit-specific options.
      */