@midscene/core 1.16.0 → 1.16.1

package/dist/es/agent/agent.mjs

@@ -1,17 +1,11 @@
 import { resolveModelForTask } from "../ai-model/models/task-routing.mjs";
 import { INTERNAL_CALL_ID_FIELD } from "../ai-model/service-caller/index.mjs";
-import { IS_REPORT_BUILD } from "../constants.mjs";
 import js_yaml from "js-yaml";
-import { generateTestRunReportScriptTag } from "../dump/html-utils.mjs";
 import { ScreenshotItem } from "../screenshot-item.mjs";
 import service from "../service/index.mjs";
-import { waitForResourceIdle } from "../test-runner/engine/resource-operations.mjs";
-import { buildAgentTestRunReportDump } from "../test-runner/reporting/agent-report.mjs";
-import { executionRecordsToReportInput } from "../test-runner/reporting/execution-record.mjs";
-import { ExecutionDump, ReportActionDump } from "../types.mjs";
-import { YamlExecutionOwnershipError, currentYamlSignal, enterYamlAction, enterYamlExecution, runInYamlExecutionContext } from "../yaml/execution-session.mjs";
-import { ReportGenerator, assertReportGenerationOptions } from "../report-generator.mjs";
-import { getVersion, processCacheConfig, reportHTMLContent } from "../utils.mjs";
+import { hasPendingResourceOperation, waitForResourceIdle } from "../test-runner/engine/resource-operations.mjs";
+import { ExecutionDump } from "../types.mjs";
+import { YamlExecutionOwnershipError, currentYamlSignal, enterYamlAction, enterYamlExecution, hasActiveYamlExecution, runInYamlExecutionContext } from "../yaml/execution-session.mjs";
 import { ScriptPlayer, buildDetailedLocateParam, buildDetailedLocateParamAndRestParams, parseYamlScript } from "../yaml/index.mjs";
 import { readFile } from "node:fs/promises";
 import { basename, resolve as external_node_path_resolve } from "node:path";
@@ -20,10 +14,12 @@ import { serializeError } from "@midscene/shared/agent-tools/error-formatter";
 import { observationArtifactAdapterSymbol } from "@midscene/shared/agent-tools/observation-artifact";
 import { MIDSCENE_REPLANNING_CYCLE_LIMIT, ModelConfigManager, globalConfigManager, globalModelConfigManager } from "@midscene/shared/env";
 import { getDebug } from "@midscene/shared/logger";
-import { assert, ifInBrowser, uuid } from "@midscene/shared/utils";
+import { assert, uuid } from "@midscene/shared/utils";
 import { defineActionRegisterFileChooserAccept, defineActionSleep } from "../device/index.mjs";
 import { ActionReadiness, isActionReadinessError } from "./action-readiness.mjs";
-import { validateAgentCacheInput } from "./cache-config.mjs";
+import { normalizeAgentOptions, withAgentDefaults } from "./agent-options.mjs";
+import { AgentReportManager } from "./agent-report-manager.mjs";
+import { normalizeAgentCacheConfig } from "./cache-config.mjs";
 import { FileChooserAccepter } from "./file-chooser.mjs";
 import { Insight } from "./insight.mjs";
 import { MetricsCollector } from "./metrics.mjs";
@@ -37,7 +33,7 @@ import { TaskExecutor, locatePlanForLocate, withFileChooser } from "./tasks.mjs"
 import { commonAgentTestRunnerNodeDefinitions } from "./test-runner-nodes.mjs";
 import { UIObservationImpl, UIObserverImpl, uiContextFromObservationRecord } from "./ui-observer.mjs";
 import { locateParamStr, paramStr, taskTitleStr, typeStr } from "./ui-utils.mjs";
-import { commonContextParser, getReportFileName, normalizeFilePaths, normalizeScrollType } from "./utils.mjs";
+import { commonContextParser, normalizeFilePaths, normalizeScrollType } from "./utils.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -67,66 +63,38 @@ class Agent {
     static getTestRunnerNodeDefinitions() {
         return commonAgentTestRunnerNodeDefinitions;
     }
+    get dump() {
+        return this.reportManager.dump;
+    }
+    set dump(value) {
+        this.reportManager.dump = value;
+    }
+    get reportFile() {
+        return this.reportManager.reportFile;
+    }
+    set reportFile(value) {
+        this.reportManager.reportFile = value;
+    }
+    get reportFileName() {
+        return this.reportManager.reportFileName;
+    }
+    set reportFileName(value) {
+        this.reportManager.reportFileName = value;
+    }
     _prepareForTestRunner() {
-        this.reportGenerator.enableSourceSnapshots?.();
+        this.reportManager._prepareForTestRunner();
     }
     async _createReportSource(scopeId, executionIds) {
-        return this.reportGenerator.createSourceSnapshot?.(scopeId, executionIds);
+        return this.reportManager._createReportSource(scopeId, executionIds);
     }
     async _writeYamlExecutionReport(record) {
-        const existingIndex = this.yamlExecutionRecords.findIndex((entry)=>entry.runId === record.runId);
-        const recordIndex = existingIndex < 0 ? this.yamlExecutionRecords.length : existingIndex;
-        this.yamlExecutionRecords[recordIndex] = record;
-        try {
-            const path = await this.reportGenerator.writeRunnerReport?.(this.buildYamlReportInput(), this.yamlReportScopeId, this.getReportMeta());
-            this.reportFile = path ?? this.reportFile;
-            return path;
-        } catch (error) {
-            this.yamlExecutionRecords[recordIndex] = Object.freeze({
-                ...record,
-                status: 'failed',
-                reportError: error
-            });
-            throw error;
-        }
-    }
-    buildYamlReportInput() {
-        const scopedRecords = this.yamlExecutionRecords.map((entry)=>({
-                ...entry,
-                ...entry.execution ? {
-                    execution: {
-                        document: {
-                            ...entry.execution.document,
-                            reportScopeId: this.yamlReportScopeId
-                        },
-                        cases: entry.execution.cases.map((outcome)=>({
-                                ...outcome,
-                                ...outcome.run ? {
-                                    run: {
-                                        ...outcome.run,
-                                        reportScopeId: this.yamlReportScopeId
-                                    }
-                                } : {},
-                                ...outcome.attempts ? {
-                                    attempts: outcome.attempts.map((attempt)=>({
-                                            ...attempt,
-                                            reportScopeId: this.yamlReportScopeId
-                                        }))
-                                } : {}
-                            }))
-                    }
-                } : {}
-            }));
-        return executionRecordsToReportInput(scopedRecords, {
-            runId: this.yamlReportScopeId
-        });
+        return this.reportManager._writeYamlExecutionReport(record);
     }
     get onDumpUpdate() {
-        return this.dumpUpdateListeners[0];
+        return this.reportManager.onDumpUpdate;
     }
     set onDumpUpdate(callback) {
-        this.dumpUpdateListeners = [];
-        if (callback) this.dumpUpdateListeners.push(callback);
+        this.reportManager.onDumpUpdate = callback;
     }
     get aiContexts() {
         if (!this.opts.aiContexts) this.opts.aiContexts = {};
@@ -171,7 +139,9 @@ class Agent {
         };
     }
     createInsight(getUIContext) {
-        return new Insight(this.taskExecutor, (task)=>this.resolveModelRuntime('insight', task), (apiName, callContext)=>this.resolveUserContext(apiName, callContext), getUIContext);
+        return new Insight({
+            createTypeQueryExecution: (...args)=>this.withReportOperation(()=>this.taskExecutor.createTypeQueryExecution(...args))
+        }, (task)=>this.resolveModelRuntime('insight', task), (apiName, callContext)=>this.resolveUserContext(apiName, callContext), getUIContext);
     }
     async getActionSpace() {
         return this.fullActionSpace;
@@ -204,6 +174,7 @@ class Agent {
         return await this.getUIContext('locate');
     }
     async startObserving(opt) {
+        this.assertReportWritable();
         assert(!this.frozenUIContext, 'startObserving() cannot be used while the UI context is frozen (call unfreezePageContext() first)');
         assert(!this.activeObserver, "An observation window is already active on this agent. Stop the existing observer first (await observer.stop()) before starting a new one.");
         const observer = new UIObserverImpl({
@@ -251,31 +222,20 @@ class Agent {
             this.opts.aiActionContext = context;
         }
     }
-    resetDump() {
-        this.dump = new ReportActionDump({
-            sdkVersion: getVersion(),
-            groupName: this.opts.groupName,
-            groupDescription: this.opts.groupDescription,
-            executions: [],
-            modelBriefs: [],
-            deviceType: this.interface.interfaceType
-        });
-        this.executionDumpIndexByRunner = new WeakMap();
-        return this.dump;
+    assertReportWritable() {
+        this.reportManager.assertReportWritable();
+    }
+    async withReportOperation(operation) {
+        return this.reportManager.withReportOperation(operation);
+    }
+    async resetDump() {
+        return this.reportManager.resetDump();
+    }
+    async finalizeReport() {
+        return this.reportManager.finalizeReport();
     }
     appendExecutionDump(execution, runner) {
-        const currentDump = this.dump;
-        if (runner) {
-            const existingIndex = this.executionDumpIndexByRunner.get(runner);
-            if (void 0 !== existingIndex) {
-                currentDump.executions[existingIndex] = execution;
-                return;
-            }
-            currentDump.executions.push(execution);
-            this.executionDumpIndexByRunner.set(runner, currentDump.executions.length - 1);
-            return;
-        }
-        currentDump.executions.push(execution);
+        this.reportManager.appendExecutionDump(execution, runner);
     }
     collectUsageMetrics(execution) {
         for (const task of execution.tasks){
@@ -300,50 +260,16 @@ class Agent {
         return this.metricsCollector.snapshot();
     }
     dumpDataString(opt) {
-        this.dump.groupName = this.opts.groupName;
-        this.dump.groupDescription = this.opts.groupDescription;
-        if (ifInBrowser || opt?.inlineScreenshots) return this.dump.serializeWithInlineScreenshots();
-        return this.dump.serialize();
+        return this.reportManager.dumpDataString(opt);
     }
     reportHTMLString(opt) {
-        if (IS_REPORT_BUILD) return '';
-        const dumpString = this.dumpDataString(opt);
-        if (!this.yamlExecutionRecords.length) return reportHTMLContent(dumpString);
-        const reportId = this.yamlReportScopeId;
-        const runnerDump = buildAgentTestRunReportDump(this.buildYamlReportInput(), this.dump, {
-            reportId,
-            scopeId: this.yamlReportScopeId,
-            sourcePath: this.reportFile ?? '<inline-agent-report>'
-        });
-        return `${reportHTMLContent({
-            dumpString,
-            attributes: {
-                'data-group-id': reportId,
-                'data-report-id': reportId
-            }
-        })}\n${generateTestRunReportScriptTag(runnerDump)}`;
+        return this.reportManager.reportHTMLString(()=>this.dumpDataString(opt));
     }
     writeOutActionDumps(executionDump) {
-        const exec = executionDump || this.lastExecutionDump;
-        if (exec) {
-            this.lastExecutionDump = exec;
-            this.reportGenerator.onExecutionUpdate(exec, this.getReportMeta(), this.opts.reportAttributes);
-        }
-        this.reportFile = this.reportGenerator.getReportPath();
+        this.reportManager.writeOutActionDumps(executionDump);
     }
     async flushReport() {
-        this.writeOutActionDumps();
-        await this.reportGenerator.flush();
-        return this.lastExecutionDump ? this.reportFile ?? void 0 : void 0;
-    }
-    getReportMeta() {
-        return {
-            groupName: this.dump.groupName,
-            groupDescription: this.dump.groupDescription,
-            sdkVersion: this.dump.sdkVersion,
-            modelBriefs: this.dump.modelBriefs,
-            deviceType: this.dump.deviceType
-        };
+        return this.reportManager.flushReport();
     }
     async callbackOnTaskStartTip(task) {
         const param = paramStr(task);
@@ -354,6 +280,9 @@ class Agent {
         return async (param)=>await this.callActionInActionSpace(name, param);
     }
     async callActionInActionSpace(type, opt, abortSignal) {
+        return this.withReportOperation(()=>this.executeActionInActionSpace(type, opt, abortSignal));
+    }
+    async executeActionInActionSpace(type, opt, abortSignal) {
         debug('callActionInActionSpace', type, ',', opt);
         const clonedActionParam = opt && 'object' == typeof opt && !Array.isArray(opt) ? {
             ...opt
@@ -376,12 +305,14 @@ class Agent {
         return output;
     }
     async aiTap(locatePrompt, opt) {
-        assert(locatePrompt, 'missing locate prompt for tap');
-        const detailedLocateParam = buildDetailedLocateParam(locatePrompt, this.withContext('aiTap', opt));
-        const fileChooserAccept = opt?.fileChooserAccept ? this.normalizeFileInput(opt.fileChooserAccept) : void 0;
-        await withFileChooser(this.interface, fileChooserAccept, async ()=>{
-            await this.callActionInActionSpace('Tap', {
-                locate: detailedLocateParam
+        await this.withReportOperation(async ()=>{
+            assert(locatePrompt, 'missing locate prompt for tap');
+            const detailedLocateParam = buildDetailedLocateParam(locatePrompt, this.withContext('aiTap', opt));
+            const fileChooserAccept = opt?.fileChooserAccept ? this.normalizeFileInput(opt.fileChooserAccept) : void 0;
+            await withFileChooser(this.interface, fileChooserAccept, async ()=>{
+                await this.callActionInActionSpace('Tap', {
+                    locate: detailedLocateParam
+                });
             });
         });
     }
@@ -512,6 +443,9 @@ class Agent {
         });
     }
     async aiAct(taskPrompt, opt) {
+        return this.withReportOperation(()=>this.executeAiAct(taskPrompt, opt));
+    }
+    async executeAiAct(taskPrompt, opt) {
         const internalOptions = opt;
         const internalReportDisplay = internalOptions?._internalReportDisplay;
         const taskPromptText = 'string' == typeof taskPrompt ? taskPrompt : taskPrompt.prompt;
@@ -619,6 +553,9 @@ class Agent {
         return result;
     }
     async runMarkdown(markdownPath, opt) {
+        return this.withReportOperation(()=>this.executeMarkdown(markdownPath, opt));
+    }
+    async executeMarkdown(markdownPath, opt) {
         const markdown = await readFile(markdownPath, 'utf-8');
         const { prompt } = await markdownToAiActPrompt(markdown, markdownPath);
         return this.aiAct(prompt, {
@@ -630,7 +567,7 @@ class Agent {
         });
     }
     async runGherkinScenario(scenarioText, opt) {
-        return runGherkinScenario(this, scenarioText, opt);
+        return this.withReportOperation(()=>runGherkinScenario(this, scenarioText, opt));
     }
     async aiAction(taskPrompt, opt) {
         return this.aiAct(taskPrompt, opt);
@@ -651,6 +588,9 @@ class Agent {
         return this.createInsight().aiAsk(prompt, opt);
     }
     async aiLocate(prompt, opt) {
+        return this.withReportOperation(()=>this.executeLocate(prompt, opt));
+    }
+    async executeLocate(prompt, opt) {
         const locateParam = buildDetailedLocateParam(prompt, this.withContext('aiLocate', opt));
         assert(locateParam, 'cannot get locate param for aiLocate');
         const locatePlan = locatePlanForLocate(locateParam);
@@ -680,16 +620,19 @@ class Agent {
     async aiWaitFor(assertion, opt) {
         const modelRuntime = this.resolveModelRuntime('insight', 'boolean');
         const options = this.withContext('aiWaitFor', opt);
-        await this.taskExecutor.waitFor(assertion, {
-            ...options,
-            timeoutMs: options?.timeoutMs || 15000,
-            checkIntervalMs: options?.checkIntervalMs || 3000
-        }, modelRuntime);
+        await this.withReportOperation(()=>this.taskExecutor.waitFor(assertion, {
+                ...options,
+                timeoutMs: options?.timeoutMs || 15000,
+                checkIntervalMs: options?.checkIntervalMs || 3000
+            }, modelRuntime));
     }
     async ai(...args) {
         return this.aiAct(...args);
     }
     async runYaml(yamlScriptContent, options) {
+        return this.withReportOperation(()=>this.executeYaml(yamlScriptContent, options));
+    }
+    async executeYaml(yamlScriptContent, options) {
         if (this.destroyed) throw new Error('Cannot run YAML using a destroyed Agent.');
         const script = parseYamlScript(yamlScriptContent, 'yaml');
         const player = new ScriptPlayer(script, async ()=>({
@@ -709,20 +652,16 @@ class Agent {
     }
     async evaluateJavaScript(script) {
         assert(this.interface.evaluateJavaScript, 'evaluateJavaScript is not supported in current agent');
-        return this.interface.evaluateJavaScript(script);
+        return this.withReportOperation(()=>this.interface.evaluateJavaScript(script));
     }
     addDumpUpdateListener(listener) {
-        this.dumpUpdateListeners.push(listener);
-        return ()=>{
-            this.removeDumpUpdateListener(listener);
-        };
+        return this.reportManager.addDumpUpdateListener(listener);
     }
     removeDumpUpdateListener(listener) {
-        const index = this.dumpUpdateListeners.indexOf(listener);
-        if (index > -1) this.dumpUpdateListeners.splice(index, 1);
+        this.reportManager.removeDumpUpdateListener(listener);
     }
     clearDumpUpdateListeners() {
-        this.dumpUpdateListeners = [];
+        this.reportManager.clearDumpUpdateListeners();
     }
     addProgressListener(listener) {
         return this.progressBus.subscribe(listener);
@@ -734,17 +673,13 @@ class Agent {
         this.progressBus.clear();
     }
     notifyDumpUpdateListeners(executionDump) {
-        const dumpString = this.dumpDataString();
-        for (const listener of this.dumpUpdateListeners)try {
-            listener(dumpString, executionDump);
-        } catch (error) {
-            console.error('Error in onDumpUpdate listener', error);
-        }
+        this.reportManager.notifyDumpUpdateListeners(executionDump);
     }
     async destroy() {
         if (this.destroyed) return;
         this.destroyed = true;
         await waitForResourceIdle(this);
+        await this.reportManager.waitForOperations();
         for (const observer of this.ownedObservers)try {
             await observer.dispose();
         } catch (error) {
@@ -758,17 +693,18 @@ class Agent {
         } catch (error) {
             interfaceDestroyError = error;
         }
-        await this.reportGenerator.flush();
-        const finalPath = await this.reportGenerator.finalize();
-        this.reportFile = finalPath;
-        this.resetDump();
+        await this.reportManager.waitForReset();
+        if (!hasActiveYamlExecution(this)) await this.finalizeReport();
         if (interfaceDestroyError) throw interfaceDestroyError;
     }
     async sleep(ms, options) {
         options?.abortSignal?.throwIfAborted();
-        await this.taskExecutor.sleep(ms, options?.abortSignal);
+        await this.withReportOperation(()=>this.taskExecutor.sleep(ms, options?.abortSignal));
     }
     async recordToReport(title, opt) {
+        return this.withReportOperation(()=>this.writeRecordToReport(title, opt));
+    }
+    async writeRecordToReport(title, opt) {
         const now = Date.now();
         const screenshots = opt?.screenshots;
         const screenshotBase64 = opt?.screenshotBase64;
@@ -826,10 +762,13 @@ class Agent {
         });
         this.appendExecutionDump(executionDump);
         this.writeOutActionDumps(executionDump);
-        await this.reportGenerator.flush();
+        await this.reportManager.flushPendingWrites();
         this.notifyDumpUpdateListeners(executionDump);
     }
     async recordErrorToReport(title, opt) {
+        return this.withReportOperation(()=>this.writeErrorToReport(title, opt));
+    }
+    async writeErrorToReport(title, opt) {
         const now = Date.now();
         const error = serializeError(opt.error);
         const recorder = [];
@@ -869,7 +808,7 @@ class Agent {
         });
         this.appendExecutionDump(executionDump);
         this.writeOutActionDumps(executionDump);
-        await this.reportGenerator.flush();
+        await this.reportManager.flushPendingWrites();
         this.notifyDumpUpdateListeners(executionDump);
     }
     async logScreenshot(title, opt) {
@@ -895,25 +834,6 @@ class Agent {
         this.frozenUIContext = void 0;
         debug('Page context unfrozen successfully');
     }
-    processCacheConfig(opts) {
-        validateAgentCacheInput(opts.cache);
-        const cacheConfig = processCacheConfig(opts.cache, opts.cacheId || 'default');
-        if (!cacheConfig) return null;
-        if ('object' == typeof cacheConfig && null !== cacheConfig) {
-            const id = cacheConfig.id;
-            const strategyValue = cacheConfig.strategy ?? 'read-write';
-            const isReadOnly = 'read-only' === strategyValue;
-            const isWriteOnly = 'write-only' === strategyValue;
-            return {
-                id,
-                enabled: !isWriteOnly,
-                readOnly: isReadOnly,
-                writeOnly: isWriteOnly,
-                cacheDir: cacheConfig.cacheDir?.trim()
-            };
-        }
-        return null;
-    }
     normalizeFileInput(files) {
         const filesArray = Array.isArray(files) ? files : [
             files
@@ -927,11 +847,7 @@ class Agent {
     constructor(interfaceInstance, opts){
         _define_property(this, "interface", void 0);
         _define_property(this, "service", void 0);
-        _define_property(this, "dump", void 0);
-        _define_property(this, "reportFile", void 0);
-        _define_property(this, "reportFileName", void 0);
-        _define_property(this, "yamlReportScopeId", uuid());
-        _define_property(this, "yamlExecutionRecords", []);
+        _define_property(this, "reportManager", void 0);
         _define_property(this, "taskExecutor", void 0);
         _define_property(this, "opts", void 0);
         _define_property(this, "dryMode", false);
@@ -940,7 +856,6 @@ class Agent {
         _define_property(this, "metricsCollector", new MetricsCollector());
         _define_property(this, "usageCallCounter", 0);
         _define_property(this, "countedUsageKeys", new Set());
-        _define_property(this, "dumpUpdateListeners", []);
         _define_property(this, "progressBus", new AgentProgressBus());
         _define_property(this, "destroyed", false);
         _define_property(this, "actionReadiness", void 0);
@@ -948,44 +863,17 @@ class Agent {
         _define_property(this, "frozenUIContext", void 0);
         _define_property(this, "activeObserver", null);
         _define_property(this, "ownedObservers", new Set());
-        _define_property(this, "executionDumpIndexByRunner", new WeakMap());
         _define_property(this, "fullActionSpace", void 0);
         _define_property(this, "activeFileChooserAccepter", void 0);
         _define_property(this, "activeFileChooserAllowedDir", void 0);
-        _define_property(this, "reportGenerator", void 0);
-        _define_property(this, "lastExecutionDump", void 0);
         this.interface = interfaceInstance;
-        this.opts = Object.assign({
-            generateReport: true,
-            persistExecutionDump: false,
-            autoPrintReportMsg: true,
-            groupName: 'Midscene Report',
-            groupDescription: ''
-        }, opts || {});
-        assertReportGenerationOptions(this.opts);
+        this.opts = withAgentDefaults(opts);
         if (void 0 !== this.opts.waitForActionReady) this.actionReadiness = new ActionReadiness(this.opts.waitForActionReady);
-        if (void 0 !== this.opts.aiContexts && ('object' != typeof this.opts.aiContexts || null === this.opts.aiContexts || Array.isArray(this.opts.aiContexts))) throw new TypeError('opts.aiContexts must be a plain object');
-        for (const [key, value] of Object.entries(this.opts.aiContexts ?? {})){
-            if (!isAgentAIContextKey(key)) throw new TypeError(`Unknown Agent context key: ${key}`);
-            if (void 0 !== value && 'string' != typeof value) throw new TypeError(`Agent context "${key}" must be a string`);
-        }
-        const deprecatedAiActContextOption = void 0 !== this.opts.aiActContext ? 'aiActContext' : void 0 !== this.opts.aiActionContext ? 'aiActionContext' : void 0;
-        if (deprecatedAiActContextOption) warn(`Agent option "${deprecatedAiActContextOption}" is deprecated; use "aiContexts.aiAct" instead. When both are provided, "aiContexts.aiAct" takes precedence.`);
-        const normalizedAIContexts = {
-            ...this.opts.aiContexts
-        };
-        const resolvedAiActContext = normalizedAIContexts.aiAct ?? this.opts.aiActContext ?? this.opts.aiActionContext;
-        if (void 0 !== resolvedAiActContext) {
-            normalizedAIContexts.aiAct = resolvedAiActContext;
-            this.opts.aiActContext = resolvedAiActContext;
-            this.opts.aiActionContext = resolvedAiActContext;
-        }
-        this.opts.aiContexts = normalizedAIContexts;
-        if (opts?.modelConfig && ('object' != typeof opts?.modelConfig || Array.isArray(opts.modelConfig))) throw new Error(`opts.modelConfig must be a plain object map of env keys to values, but got ${typeof opts?.modelConfig}`);
+        normalizeAgentOptions(this.opts, warn);
         this.modelConfigManager = opts?.modelConfig ? new ModelConfigManager(opts.modelConfig, opts.createOpenAIClient) : opts?.createOpenAIClient ? new AgentScopedModelConfigManager(globalModelConfigManager, opts.createOpenAIClient) : globalModelConfigManager;
         this.onTaskStartTip = this.opts.onTaskStartTip;
         this.service = new service(async ()=>this.getUIContext());
-        const cacheConfigObj = this.processCacheConfig(opts || {});
+        const cacheConfigObj = normalizeAgentCacheConfig(opts || {});
         if (cacheConfigObj) this.taskCache = new TaskCache(cacheConfigObj.id, cacheConfigObj.enabled, void 0, {
             readOnly: cacheConfigObj.readOnly,
             writeOnly: cacheConfigObj.writeOnly,
@@ -1016,30 +904,26 @@ class Agent {
             operationResource: this,
             actionSpace: this.fullActionSpace,
             hooks: {
+                onExecutionCreated: (runner)=>{
+                    this.reportManager.bindRunner(runner);
+                },
                 onSnapshotChange: async (runner)=>{
+                    this.reportManager.assertRunnerCurrent(runner);
                     const executionDump = runner.dump();
                     this.appendExecutionDump(executionDump, runner);
                     this.collectUsageMetrics(executionDump);
                     this.writeOutActionDumps(executionDump);
-                    await this.reportGenerator.flush();
-                    const dumpString = this.dumpDataString();
-                    for (const listener of this.dumpUpdateListeners)try {
-                        listener(dumpString, executionDump);
-                    } catch (error) {
-                        console.error('Error in onDumpUpdate listener', error);
-                    }
+                    await this.reportManager.flushPendingWrites();
+                    this.reportManager.notifyDumpUpdateListeners(executionDump);
                 },
                 onProgress: this.progressBus.publish
             }
         });
-        this.dump = this.resetDump();
-        this.reportFileName = opts?.reportFileName ?? getReportFileName(opts?.testId || this.interface.interfaceType || 'web');
-        this.reportGenerator = ReportGenerator.create(this.reportFileName, {
-            generateReport: this.opts.generateReport,
-            persistExecutionDump: this.opts.persistExecutionDump,
-            outputFormat: this.opts.outputFormat,
-            autoPrintReportMsg: this.opts.autoPrintReportMsg,
-            reuseExistingReport: this.opts.reportAttributes?.['data-group-id'] === this.reportFileName
+        this.reportManager = new AgentReportManager({
+            getOptions: ()=>this.opts,
+            getDeviceType: ()=>this.interface.interfaceType,
+            isDestroyed: ()=>this.destroyed,
+            isExternallyBusy: ()=>Boolean(this.activeObserver) || hasActiveYamlExecution(this) || hasPendingResourceOperation(this)
         });
         Object.defineProperty(this, observationArtifactAdapterSymbol, {
             value: {