@loadmill/droid-cua 2.10.0 → 2.10.1-rc.8

package/build/src/core/execution-engine.js

@@ -1,21 +1,28 @@
 import { randomUUID } from "node:crypto";
-import path from "path";
-import { writeFile } from "fs/promises";
 import { getScreenshotAsBase64, getCurrentPlatform } from "../device/connection.js";
+import { getBrowserInfo, navigateToUrl as navigateBrowserToUrl } from "../browser/connection.js";
 import { handleModelAction } from "../device/actions.js";
 import { sendCUARequest } from "../device/openai.js";
+import { executeLoadmillInstruction } from "../device/loadmill.js";
 import { emitDesktopDebug } from "../utils/desktop-debug.js";
 import { getConfiguredStepDelayMs } from "../utils/step-delay.js";
 import { printCliOutput } from "../utils/console-output.js";
-import { annotateScreenshotArtifact, createAnnotatedScreenshotFromBase64 } from "../utils/run-screenshot-recorder.js";
 import { CAPTURE_SOURCES } from "./capture-sources.js";
+import { ScreenshotStore } from "./screenshot-store.js";
+import { handlePreviewClick } from "./tool-handlers/preview-click.js";
+import { handleNavigateToolCall } from "./tool-handlers/navigate.js";
+import { handleAssertionToolCall } from "./tool-handlers/assert.js";
+import { handleLoadmillToolCall } from "./tool-handlers/loadmill.js";
+import { handleTestDesignCompleteToolCall } from "./tool-handlers/test-design-complete.js";
+import { buildDebugContext, buildTextToolOutputItem, } from "./tool-handlers/utils.js";
 function extractActionableOutputItems(items) {
     const entries = [];
     for (const item of items) {
-        if (item?.type === "function_call" && item.name === "preview_click") {
+        if (item?.type === "function_call") {
             entries.push({
-                type: "preview_click",
+                type: "function_call",
                 call_id: item.call_id || item.id,
+                name: item.name,
                 arguments: item.arguments,
             });
             continue;
@@ -42,311 +49,81 @@ function extractActionableOutputItems(items) {
     }
     return entries;
 }
-function buildPreviewClickValidationError(argumentsText) {
-    if (!argumentsText || typeof argumentsText !== "string") {
-        return "Invalid preview_click arguments: expected a JSON object with numeric x and y.";
-    }
-    return `Invalid preview_click arguments: ${argumentsText}`;
-}
-function parsePreviewClickArguments(argumentsText) {
-    let parsedArguments;
-    try {
-        parsedArguments = JSON.parse(argumentsText);
-    }
-    catch {
-        return {
-            ok: false,
-            message: buildPreviewClickValidationError("arguments could not be parsed as JSON; expected numeric x and y."),
-        };
-    }
-    const x = parsedArguments?.x;
-    const y = parsedArguments?.y;
-    if (!Number.isFinite(x) || !Number.isFinite(y)) {
-        return {
-            ok: false,
-            message: buildPreviewClickValidationError("x and y must both be numeric."),
-        };
-    }
-    return {
-        ok: true,
-        x,
-        y,
-    };
-}
-function buildFunctionCallOutputItem(callId, output) {
-    return {
-        type: "function_call_output",
-        call_id: callId,
-        output,
-    };
-}
-function buildPreviewOutputText({ requestedX, requestedY, renderedX, renderedY, wasClamped }) {
-    const baseText = `Marker placed at (${renderedX}, ${renderedY}) on the current screen. The click has not been executed.`;
-    if (!wasClamped) {
-        return baseText;
-    }
-    return `${baseText} Requested point (${requestedX}, ${requestedY}) was off-screen; marker rendered at (${renderedX}, ${renderedY}).`;
-}
-function buildPreviewOutputContent({ text, annotatedScreenshotBase64 = null }) {
-    const content = [{
-            type: "input_text",
-            text,
-        }];
-    if (annotatedScreenshotBase64) {
-        content.push({
-            type: "input_image",
-            image_url: `data:image/png;base64,${annotatedScreenshotBase64}`,
-            detail: "high",
-        });
-    }
-    return content;
-}
-function buildDebugContext(context = null, stepContext = null) {
-    return {
-        scope: context?.sessionId ? "design" : "execution",
-        runId: context?.runId,
-        sessionId: context?.sessionId,
-        stepId: stepContext?.stepId,
-        instructionIndex: stepContext?.instructionIndex
-    };
-}
 function collectPendingSafetyChecks(items = []) {
     return items
         .filter((item) => item.type === "pending_safety_check")
         .map((item) => ({ id: item.id }));
 }
-function normalizeArtifactPaths(result) {
-    if (result && typeof result === "object" && !Array.isArray(result)) {
-        if (Array.isArray(result.annotationSourcePaths)) {
-            return normalizeArtifactPaths(result.annotationSourcePaths);
-        }
-        return normalizeArtifactPaths(result.artifactPaths);
-    }
-    if (Array.isArray(result)) {
-        return result.filter((value) => typeof value === "string" && value.trim());
-    }
-    if (typeof result === "string" && result.trim()) {
-        return [result];
-    }
-    return [];
-}
-function screenshotPathFromRecorderResult(result) {
-    if (result && typeof result === "object" && !Array.isArray(result)) {
-        return typeof result.screenshotPath === "string" && result.screenshotPath.trim()
-            ? result.screenshotPath
-            : null;
-    }
-    return typeof result === "string" && result.trim() ? result : null;
-}
-function screenshotDataUrlFromRecorderResult(result) {
-    if (result && typeof result === "object" && !Array.isArray(result)) {
-        return typeof result.screenshotDataUrl === "string" && result.screenshotDataUrl.trim()
-            ? result.screenshotDataUrl
-            : null;
-    }
-    return null;
-}
 export class ExecutionEngine {
     constructor(session, options = {}) {
         this.session = session;
         this.recordScreenshots = options.recordScreenshots || false;
         this.screenshotDir = options.screenshotDir || null;
         this.screenshotRecorder = options.screenshotRecorder || null;
+        this.screenshotStore = options.screenshotStore || new ScreenshotStore({
+            recordScreenshots: this.recordScreenshots,
+            screenshotDir: this.screenshotDir,
+            screenshotRecorder: this.screenshotRecorder,
+        });
         this.stepDelayMs = options.stepDelayMs ?? getConfiguredStepDelayMs();
-        this.reportedScreenshotWriteError = false;
-        this.reportedScreenshotAnnotateError = false;
-        this.lastRecordedScreenshotPaths = [];
         this.getScreenshotAsBase64 = options.getScreenshotAsBase64 || getScreenshotAsBase64;
         this.handleModelAction = options.handleModelAction || handleModelAction;
         this.sendCUARequest = options.sendCUARequest || sendCUARequest;
         this.reviseTestScript = options.reviseTestScript || null;
         this.getCurrentPlatform = options.getCurrentPlatform || getCurrentPlatform;
-    }
-    async saveScreenshotArtifact(screenshotBase64, metadata = {}, options = {}) {
-        if (typeof screenshotBase64 !== "string" || !screenshotBase64) {
-            return null;
-        }
-        const updateLastRecordedScreenshotPaths = options.updateLastRecordedScreenshotPaths !== false;
-        const previousRecordedScreenshotPaths = updateLastRecordedScreenshotPaths
-            ? null
-            : [...this.lastRecordedScreenshotPaths];
-        try {
-            if (this.screenshotRecorder?.saveScreenshot) {
-                const result = await this.screenshotRecorder.saveScreenshot(screenshotBase64, metadata);
-                if (updateLastRecordedScreenshotPaths) {
-                    this.lastRecordedScreenshotPaths = normalizeArtifactPaths(result);
-                }
-                return result;
-            }
-            if (this.recordScreenshots && this.screenshotDir) {
-                const framePath = path.join(this.screenshotDir, `frame_${String(Date.now())}.png`);
-                await writeFile(framePath, Buffer.from(screenshotBase64, "base64"));
-                if (updateLastRecordedScreenshotPaths) {
-                    this.lastRecordedScreenshotPaths = [framePath];
-                }
-                return framePath;
-            }
-        }
-        catch (error) {
-            if (updateLastRecordedScreenshotPaths) {
-                this.lastRecordedScreenshotPaths = [];
-            }
-            else {
-                this.lastRecordedScreenshotPaths = previousRecordedScreenshotPaths;
-            }
-            if (!this.reportedScreenshotWriteError) {
-                this.reportedScreenshotWriteError = true;
-                const scope = typeof metadata.sessionId === "string" ? "design" : "execution";
-                const ids = scope === "design"
-                    ? {
-                        sessionId: metadata.sessionId,
-                        stepId: metadata.stepId,
-                        instructionIndex: metadata.instructionIndex
-                    }
-                    : {
-                        runId: metadata.runId,
-                        stepId: metadata.stepId,
-                        instructionIndex: metadata.instructionIndex
-                    };
-                emitDesktopDebug("run.screenshot_write.error", scope, ids, {
-                    captureSource: metadata.captureSource ?? null,
-                    message: error instanceof Error ? error.message : "Failed to persist screenshot"
-                });
-            }
-        }
-        return null;
+        this.getBrowserInfo = options.getBrowserInfo || getBrowserInfo;
+        this.navigateToUrl = options.navigateToUrl || navigateBrowserToUrl;
+        this.executeLoadmillInstruction = options.executeLoadmillInstruction || executeLoadmillInstruction;
+        this.toolCapabilities = options.toolCapabilities || {};
+        this.baseSystemPrompt = options.baseSystemPrompt || session?.systemPrompt || null;
+        this.isHeadlessMode = options.isHeadlessMode === true;
     }
     async recordScreenshot(screenshotBase64, metadata = {}) {
-        return await this.saveScreenshotArtifact(screenshotBase64, metadata);
+        return await this.screenshotStore.saveScreenshot(screenshotBase64, metadata);
     }
-    async recordPreviewScreenshot(screenshotBase64, metadata = {}) {
-        return await this.saveScreenshotArtifact(screenshotBase64, metadata, {
-            updateLastRecordedScreenshotPaths: false,
-        });
-    }
-    async annotateLatestScreenshot(action, metadata = {}) {
-        if (!(action?.type === "click" || action?.type === "double_click") || this.lastRecordedScreenshotPaths.length === 0) {
-            return null;
-        }
-        try {
-            const marker = {
-                x: action.x,
-                y: action.y,
-                style: "click",
-            };
-            const sourcePath = this.lastRecordedScreenshotPaths.find((filePath) => typeof filePath === "string" && filePath.trim());
-            if (sourcePath && this.screenshotRecorder?.saveAnnotatedScreenshot) {
-                return await this.screenshotRecorder.saveAnnotatedScreenshot(sourcePath, marker, metadata);
-            }
-            await Promise.all(this.lastRecordedScreenshotPaths.map((filePath) => annotateScreenshotArtifact(filePath, marker)));
+    async annotateScreenshot(currentScreenshot, action, metadata = {}) {
+        if (!(action?.type === "click" || action?.type === "double_click")) {
             return null;
         }
-        catch (error) {
-            if (!this.reportedScreenshotAnnotateError) {
-                this.reportedScreenshotAnnotateError = true;
-                const scope = typeof metadata.sessionId === "string" ? "design" : "execution";
-                const ids = scope === "design"
-                    ? {
-                        sessionId: metadata.sessionId,
-                        stepId: metadata.stepId,
-                        instructionIndex: metadata.instructionIndex
-                    }
-                    : {
-                        runId: metadata.runId,
-                        stepId: metadata.stepId,
-                        instructionIndex: metadata.instructionIndex
-                    };
-                emitDesktopDebug("run.screenshot_annotate.error", scope, ids, {
-                    actionType: action?.type ?? null,
-                    x: action?.x ?? null,
-                    y: action?.y ?? null,
-                    message: error instanceof Error ? error.message : "Failed to annotate screenshot"
-                });
-            }
-        }
-        return null;
+        return await this.screenshotStore.annotateScreenshot(currentScreenshot, { x: action.x, y: action.y, style: "click" }, { ...metadata, actionType: action.type });
     }
-    async handlePreviewClick(callId, argumentsText, context = null, stepContext = null) {
-        const parsedArguments = parsePreviewClickArguments(argumentsText);
-        if (!parsedArguments.ok) {
-            return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({ text: parsedArguments.message }));
-        }
-        try {
-            const screenshotBase64 = await this.getScreenshotAsBase64(this.session.deviceId, this.session.deviceInfo);
-            const previewResult = await createAnnotatedScreenshotFromBase64(screenshotBase64, {
-                x: parsedArguments.x,
-                y: parsedArguments.y,
-                style: "preview",
-            });
-            if (!previewResult?.screenshotBase64 || !previewResult?.marker) {
-                return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
-                    text: "preview_click failed: could not annotate the current screenshot.",
-                }));
-            }
-            const previewEventId = randomUUID();
-            const previewScreenshotResult = await this.recordPreviewScreenshot(previewResult.screenshotBase64, {
-                runId: context?.runId,
-                sessionId: context?.sessionId,
-                stepId: stepContext?.stepId,
-                instructionIndex: stepContext?.instructionIndex,
-                callId,
-                eventId: previewEventId,
-                captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
-            });
-            const previewText = buildPreviewOutputText({
-                requestedX: previewResult.marker.requestedX,
-                requestedY: previewResult.marker.requestedY,
-                renderedX: previewResult.marker.x,
-                renderedY: previewResult.marker.y,
-                wasClamped: previewResult.marker.wasClamped,
-            });
-            const addOutput = context?.addOutput || null;
-            if (addOutput) {
-                const previewScreenshotPath = screenshotPathFromRecorderResult(previewScreenshotResult);
-                const previewScreenshotDataUrl = context?.includeScreenshotDataUrl
-                    ? `data:image/png;base64,${previewResult.screenshotBase64}`
-                    : null;
-                addOutput({
-                    type: "action",
-                    text: "Click",
-                    eventType: "tool_call",
-                    runId: context?.runId,
-                    stepId: stepContext?.stepId,
-                    instructionIndex: stepContext?.instructionIndex,
-                    payload: {
-                        platform: this.session.deviceInfo?.platform,
-                        toolName: "preview_click",
-                        captureSource: CAPTURE_SOURCES.PREVIEW_CLICK,
-                        requestedX: previewResult.marker.requestedX,
-                        requestedY: previewResult.marker.requestedY,
-                        renderedX: previewResult.marker.x,
-                        renderedY: previewResult.marker.y,
-                        wasClamped: previewResult.marker.wasClamped,
-                        ...(previewScreenshotPath ? { screenshotPath: previewScreenshotPath } : {}),
-                        ...(previewScreenshotDataUrl ? { screenshotDataUrl: previewScreenshotDataUrl } : {})
-                    }
-                });
-            }
-            return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
-                text: previewText,
-                annotatedScreenshotBase64: previewResult.screenshotBase64,
-            }));
-        }
-        catch (error) {
-            return buildFunctionCallOutputItem(callId, buildPreviewOutputContent({
-                text: `preview_click failed: ${error instanceof Error ? error.message : "unable to capture or annotate the current screen."}`,
-            }));
+    /**
+     * Dispatches a function-call tool to its handler. Each handler returns a
+     * discriminated outcome that runFullTurn interprets below. Continue and
+     * close_turn outcomes may also return currentScreenshot to update the
+     * parent turn's explicit screenshot state.
+     */
+    async handleFunctionToolCall(toolName, callId, argumentsText, context = null, stepContext = null) {
+        const handlerArgs = { engine: this, callId, argumentsText, context, stepContext };
+        switch (toolName) {
+            case "preview_click":
+                return await handlePreviewClick(handlerArgs);
+            case "assert":
+                return await handleAssertionToolCall(handlerArgs);
+            case "navigate":
+                return await handleNavigateToolCall(handlerArgs);
+            case "loadmill":
+                return await handleLoadmillToolCall(handlerArgs);
+            case "test_design_complete":
+                return await handleTestDesignCompleteToolCall(handlerArgs);
+            default:
+                return {
+                    kind: "continue",
+                    outputItem: buildTextToolOutputItem(callId, `Unsupported tool call: ${toolName}`),
+                };
         }
     }
-    async requestNextTurn(messages, previousResponseId, context = null, stepContext = null) {
+    async requestNextTurn(messages, previousResponseId, context = null, stepContext = null, options = {}) {
         return await this.sendCUARequest({
             messages,
             previousResponseId,
             deviceInfo: this.session.deviceInfo,
-            debugContext: buildDebugContext(context, stepContext)
+            debugContext: options.debugContextOverride ?? buildDebugContext(context, stepContext),
+            toolCapabilities: options.toolCapabilitiesOverride ?? this.toolCapabilities,
+            includeComputerTool: options.includeComputerToolOverride ?? true,
         });
     }
-    async executeActionBatch(actions, shouldStop, context = null, stepContext = null, trackAction = null) {
+    async executeActionBatch(actions, currentScreenshot, shouldStop, context = null, stepContext = null, trackAction = null) {
         let sawExplicitScreenshotAction = false;
         for (const action of actions) {
             const actionEventId = randomUUID();
@@ -357,7 +134,7 @@ export class ExecutionEngine {
                 sawExplicitScreenshotAction = true;
                 continue;
             }
-            const annotatedScreenshotResult = await this.annotateLatestScreenshot(action, {
+            const annotatedScreenshot = await this.annotateScreenshot(currentScreenshot, action, {
                 runId: context?.runId,
                 sessionId: context?.sessionId,
                 stepId: stepContext?.stepId,
@@ -365,8 +142,6 @@ export class ExecutionEngine {
                 eventId: actionEventId,
                 captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION
             });
-            const annotatedScreenshotPath = screenshotPathFromRecorderResult(annotatedScreenshotResult);
-            const annotatedScreenshotDataUrl = screenshotDataUrlFromRecorderResult(annotatedScreenshotResult);
             await this.handleModelAction(this.session.deviceId, action, this.session.deviceInfo.scale, {
                 ...context,
                 shouldStop,
@@ -374,8 +149,8 @@ export class ExecutionEngine {
                 instructionIndex: stepContext?.instructionIndex,
                 eventId: actionEventId,
                 captureSource: CAPTURE_SOURCES.ACTION_CLICK_ANNOTATION,
-                ...(annotatedScreenshotPath ? { screenshotPath: annotatedScreenshotPath } : {}),
-                ...(context?.includeScreenshotDataUrl && annotatedScreenshotDataUrl ? { screenshotDataUrl: annotatedScreenshotDataUrl } : {})
+                ...(annotatedScreenshot?.screenshotPath ? { screenshotPath: annotatedScreenshot.screenshotPath } : {}),
+                ...(context?.includeScreenshotDataUrl && annotatedScreenshot?.screenshotDataUrl ? { screenshotDataUrl: annotatedScreenshot.screenshotDataUrl } : {})
             });
             if (trackAction) {
                 trackAction(action);
@@ -404,7 +179,7 @@ export class ExecutionEngine {
         });
         const screenshotEventId = randomUUID();
         const captureSource = sawExplicitScreenshotAction ? CAPTURE_SOURCES.CALL_OUTPUT_EXPLICIT_ACTION : CAPTURE_SOURCES.CALL_OUTPUT_POST_ACTION;
-        const screenshotResult = await this.recordScreenshot(screenshotBase64, {
+        const currentScreenshot = await this.recordScreenshot(screenshotBase64, {
             runId: context?.runId,
             sessionId: context?.sessionId,
             stepId: stepContext?.stepId,
@@ -412,7 +187,6 @@ export class ExecutionEngine {
             eventId: screenshotEventId,
             captureSource
         });
-        const screenshotPath = screenshotPathFromRecorderResult(screenshotResult);
         addOutput({
             type: "info",
             text: "Capturing screen",
@@ -423,35 +197,102 @@ export class ExecutionEngine {
                     eventId: screenshotEventId,
                     captureSource,
                     source: sawExplicitScreenshotAction ? "explicit_action" : "post_action",
-                    ...(typeof screenshotPath === "string" && screenshotPath ? { screenshotPath } : {}),
+                    ...(currentScreenshot?.screenshotPath ? { screenshotPath: currentScreenshot.screenshotPath } : {}),
                     ...(context?.includeScreenshotDataUrl
                         ? { screenshotDataUrl: `data:image/png;base64,${screenshotBase64}` }
                         : {})
                 }
             })
         });
-        return [{
-                type: "computer_call_output",
-                call_id: callId,
-                output: {
-                    type: "computer_screenshot",
-                    image_url: `data:image/png;base64,${screenshotBase64}`,
-                },
-                ...(pendingSafetyChecks.length > 0 ? { acknowledged_safety_checks: pendingSafetyChecks } : {})
-            }];
+        return {
+            input: [{
+                    type: "computer_call_output",
+                    call_id: callId,
+                    output: {
+                        type: "computer_screenshot",
+                        image_url: `data:image/png;base64,${screenshotBase64}`,
+                    },
+                    ...(pendingSafetyChecks.length > 0 ? { acknowledged_safety_checks: pendingSafetyChecks } : {})
+                }],
+            currentScreenshot,
+        };
+    }
+    emitResponseOutputItems(items, addOutput, eventMeta, options = {}) {
+        for (const item of items) {
+            if (item.type === "reasoning") {
+                for (const entry of item.summary) {
+                    if (entry.type !== "summary_text")
+                        continue;
+                    addOutput({
+                        type: "reasoning",
+                        text: entry.text,
+                        eventType: "reasoning",
+                        ...eventMeta(),
+                    });
+                    this.session.addToTranscript(`[Reasoning] ${entry.text}`);
+                }
+                continue;
+            }
+            if (item.type === "message") {
+                const textPart = item.content.find((contentItem) => contentItem.type === "output_text");
+                if (!textPart)
+                    continue;
+                if (!options.suppressAssistantOutput) {
+                    addOutput({
+                        type: "assistant",
+                        text: textPart.text,
+                        eventType: "assistant_message",
+                        ...eventMeta(),
+                    });
+                }
+                this.session.addToTranscript(`[Assistant] ${textPart.text}`);
+                continue;
+            }
+            if (item.type === "pending_safety_check") {
+                addOutput({
+                    type: "warning",
+                    text: `⚠️ Safety check: ${item.code} - ${item.message}`,
+                    eventType: "system_message",
+                    ...eventMeta({
+                        payload: {
+                            id: item.id,
+                            code: item.code,
+                            message: item.message,
+                        },
+                    }),
+                });
+            }
+        }
     }
     /**
-     * Run a full turn with the CUA model
-     * Executes actions until the model stops requesting actions
-     * Returns the new response ID for chaining
-     * @param {Object} response - The CUA response
-     * @param {Function} trackAction - Optional callback to track actions for stuck detection
-     * @param {Object} context - Optional Ink context for output
+     * Run a full turn with the CUA model. Executes actions until the model
+     * stops requesting actions, then returns { responseId, summary, currentScreenshot }.
+     *
+     * The summary's shape depends on which (if any) tool handler ran:
+     *   - assertions: summary.assertionStatus = "passed" | "failed" | "failed_skipped" | "retry"
+     *   - failures:   summary.failed = true, summary.error = string
+     *   - retries:    summary.retryInstruction = true (caller should rerun the instruction)
+     *   - navigation: summary.preserveSessionMessages = true (skip the usual message reset)
+     *
+     * @param {Object} response - The CUA response that opens this turn.
+     * @param {Function} trackAction - Optional callback for tracking actions / interrupting.
+     * @param {Object} context - Optional Ink context for output.
+     * @param {Object} options.currentScreenshot - Screenshot object to annotate during this turn.
      */
-    async runFullTurn(response, trackAction = null, context = null, stepContext = null) {
+    async runFullTurn(response, trackAction = null, context = null, stepContext = null, options = {}) {
         const addOutput = context?.addOutput || printCliOutput;
         let newResponseId = response.id;
+        let currentScreenshot = options.currentScreenshot ?? null;
         const shouldStop = () => Boolean(trackAction?.());
+        const summary = {
+            responseId: newResponseId,
+            invokedFunctionTools: [],
+            preserveSessionMessages: false,
+        };
+        const finalize = () => {
+            summary.responseId = newResponseId;
+            return { responseId: newResponseId, summary, currentScreenshot };
+        };
         const eventMeta = (extra = {}) => ({
             runId: context?.runId,
             stepId: stepContext?.stepId,
@@ -461,53 +302,12 @@ export class ExecutionEngine {
         while (true) {
             // Check for interruption before processing next batch of actions
             if (shouldStop()) {
-                return newResponseId;
+                return finalize();
             }
             const items = response.output || [];
             const actionableItems = extractActionableOutputItems(items);
             const pendingSafetyChecks = collectPendingSafetyChecks(items);
-            // ── Print assistant output ──
-            for (const item of items) {
-                if (item.type === "reasoning") {
-                    for (const entry of item.summary) {
-                        if (entry.type === "summary_text") {
-                            addOutput({
-                                type: 'reasoning',
-                                text: entry.text,
-                                eventType: 'reasoning',
-                                ...eventMeta()
-                            });
-                            this.session.addToTranscript(`[Reasoning] ${entry.text}`);
-                        }
-                    }
-                }
-                else if (item.type === "message") {
-                    const textPart = item.content.find(c => c.type === "output_text");
-                    if (textPart) {
-                        addOutput({
-                            type: 'assistant',
-                            text: textPart.text,
-                            eventType: 'assistant_message',
-                            ...eventMeta()
-                        });
-                        this.session.addToTranscript(`[Assistant] ${textPart.text}`);
-                    }
-                }
-                else if (item.type === "pending_safety_check") {
-                    addOutput({
-                        type: 'warning',
-                        text: `⚠️ Safety check: ${item.code} - ${item.message}`,
-                        eventType: 'system_message',
-                        ...eventMeta({
-                            payload: {
-                                id: item.id,
-                                code: item.code,
-                                message: item.message
-                            }
-                        })
-                    });
-                }
-            }
+            this.emitResponseOutputItems(items, addOutput, eventMeta, options);
             if (actionableItems.length === 0) {
                 // No actions = turn complete
                 break;
@@ -516,27 +316,60 @@ export class ExecutionEngine {
             if (!actionableItem?.call_id) {
                 break;
             }
-            if (actionableItem.type === "preview_click") {
-                const input = [
-                    await this.handlePreviewClick(actionableItem.call_id, actionableItem.arguments, context, stepContext),
-                ];
+            if (actionableItem.type === "function_call") {
+                const toolResult = await this.handleFunctionToolCall(actionableItem.name, actionableItem.call_id, actionableItem.arguments, context, stepContext);
+                summary.invokedFunctionTools.push(actionableItem.name);
+                if (toolResult.summaryUpdates) {
+                    Object.assign(summary, toolResult.summaryUpdates);
+                }
+                if ((toolResult.kind === "continue" || toolResult.kind === "close_turn") && toolResult.currentScreenshot) {
+                    currentScreenshot = toolResult.currentScreenshot;
+                }
                 if (shouldStop()) {
-                    return newResponseId;
+                    return finalize();
                 }
-                response = await this.requestNextTurn(input, newResponseId, context, stepContext);
+                if (toolResult.kind === "fail") {
+                    summary.failed = true;
+                    summary.error = toolResult.error;
+                    break;
+                }
+                if (toolResult.kind === "retry_instruction") {
+                    summary.retryInstruction = true;
+                    newResponseId = null;
+                    break;
+                }
+                if (toolResult.kind === "preserve_session_and_stop") {
+                    summary.preserveSessionMessages = true;
+                    newResponseId = null;
+                    break;
+                }
+                const nextTurnMessages = [toolResult.outputItem];
+                const nextTurnConfig = toolResult.nextTurnConfig ?? {};
+                if (Array.isArray(nextTurnConfig.followUpMessages) && nextTurnConfig.followUpMessages.length > 0) {
+                    nextTurnMessages.push(...nextTurnConfig.followUpMessages);
+                }
+                response = await this.requestNextTurn(nextTurnMessages, newResponseId, context, stepContext, {
+                    debugContextOverride: options.debugContextOverride,
+                    toolCapabilitiesOverride: nextTurnConfig.toolCapabilitiesOverride,
+                    includeComputerToolOverride: nextTurnConfig.includeComputerToolOverride,
+                });
                 newResponseId = response.id;
+                if (toolResult.kind === "close_turn") {
+                    break;
+                }
                 continue;
             }
             const { call_id, actions } = actionableItem;
-            const actionBatchResult = await this.executeActionBatch(actions, shouldStop, context, stepContext, trackAction);
+            const actionBatchResult = await this.executeActionBatch(actions, currentScreenshot, shouldStop, context, stepContext, trackAction);
             if (actionBatchResult.stopped) {
-                return newResponseId;
+                return finalize();
             }
-            const input = await this.buildActionFollowUp(call_id, pendingSafetyChecks, actionBatchResult.sawExplicitScreenshotAction, addOutput, eventMeta, context, stepContext);
+            const followUp = await this.buildActionFollowUp(call_id, pendingSafetyChecks, actionBatchResult.sawExplicitScreenshotAction, addOutput, eventMeta, context, stepContext);
             if (shouldStop()) {
-                return newResponseId;
+                return finalize();
             }
-            response = await this.requestNextTurn(input, newResponseId, context, stepContext);
+            currentScreenshot = followUp.currentScreenshot ?? currentScreenshot;
+            response = await this.requestNextTurn(followUp.input, newResponseId, context, stepContext);
             newResponseId = response.id;
         }
         // ── At end, if last output was only reasoning ──
@@ -549,6 +382,6 @@ export class ExecutionEngine {
                 ...eventMeta()
             });
         }
-        return newResponseId;
+        return finalize();
     }
 }