browser-debugging-daemon 1.0.0

package/orchestrator/TaskRunner.js

@@ -0,0 +1,803 @@
+import crypto from "crypto";
+import { EventEmitter } from "events";
+import { BrowserRuntime } from "../runtime/BrowserRuntime.js";
+import { BrowserSubagent } from "../subagent/BrowserSubagent.js";
+import { TaskRunStore } from "./TaskRunStore.js";
+import { RunTemplateStore } from "./RunTemplateStore.js";
+
+function nowIso() {
+    return new Date().toISOString();
+}
+
+function formatTimeoutDuration(milliseconds) {
+    if (milliseconds < 1000) {
+        return `${milliseconds}ms`;
+    }
+
+    const seconds = Math.ceil(milliseconds / 1000);
+    return `${seconds} seconds`;
+}
+
+const RUN_HISTORY_LIMIT_ENV = Number.parseInt(process.env.BROWSER_RUN_HISTORY_LIMIT, 10);
+const RULE_KINDS = new Set(["url_includes", "title_includes", "text_includes"]);
+
+function normalizePositiveInteger(value, fallback = null, minimum = 1) {
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isFinite(parsed) && parsed >= minimum) {
+        return parsed;
+    }
+    return fallback;
+}
+
+function normalizeTemplateRule(input = {}, index = 0, defaultPrefix = "Rule") {
+    const kind = typeof input.kind === "string" ? input.kind.trim().toLowerCase() : "";
+    const expected = typeof input.expected === "string"
+        ? input.expected.trim()
+        : typeof input.value === "string"
+            ? input.value.trim()
+            : "";
+    if (!RULE_KINDS.has(kind) || !expected) {
+        return null;
+    }
+    return {
+        id: typeof input.id === "string" && input.id.trim()
+            ? input.id.trim()
+            : `rule-${index + 1}`,
+        name: typeof input.name === "string" && input.name.trim()
+            ? input.name.trim()
+            : `${defaultPrefix} ${index + 1}`,
+        kind,
+        expected,
+        required: input.required !== false,
+    };
+}
+
+function normalizeTemplateRules(input, defaultPrefix) {
+    if (!Array.isArray(input)) {
+        return [];
+    }
+    return input
+        .map((rule, index) => normalizeTemplateRule(rule, index, defaultPrefix))
+        .filter(Boolean);
+}
+
+function normalizeTemplateInput(templateInput = {}, currentTemplate = null) {
+    const now = nowIso();
+    const existing = currentTemplate || null;
+    const timeoutPolicyInput = templateInput.timeoutPolicy || {};
+    const existingTimeoutPolicy = existing?.timeoutPolicy || {};
+    const timeoutPolicy = {
+        maxSteps: normalizePositiveInteger(
+            timeoutPolicyInput.maxSteps,
+            normalizePositiveInteger(existingTimeoutPolicy.maxSteps, 12),
+            1
+        ),
+        handoffTimeoutMs: normalizePositiveInteger(
+            timeoutPolicyInput.handoffTimeoutMs,
+            normalizePositiveInteger(existingTimeoutPolicy.handoffTimeoutMs, 5 * 60 * 1000),
+            1000
+        ),
+    };
+
+    const normalized = {
+        id: existing?.id || crypto.randomUUID(),
+        name: typeof templateInput.name === "string" && templateInput.name.trim()
+            ? templateInput.name.trim()
+            : existing?.name || "",
+        description: typeof templateInput.description === "string"
+            ? templateInput.description.trim()
+            : existing?.description || "",
+        taskInstruction: typeof templateInput.taskInstruction === "string"
+            ? templateInput.taskInstruction.trim()
+            : existing?.taskInstruction || "",
+        browserSource: typeof templateInput.browserSource === "string"
+            ? templateInput.browserSource.trim().toLowerCase()
+            : existing?.browserSource || "auto",
+        cdpEndpoint: typeof templateInput.cdpEndpoint === "string"
+            ? templateInput.cdpEndpoint.trim()
+            : existing?.cdpEndpoint || null,
+        startUrl: typeof templateInput.startUrl === "string"
+            ? templateInput.startUrl.trim()
+            : existing?.startUrl || "",
+        preLoginChecks: normalizeTemplateRules(
+            templateInput.preLoginChecks ?? existing?.preLoginChecks ?? [],
+            "Login Check"
+        ),
+        assertionRules: normalizeTemplateRules(
+            templateInput.assertionRules ?? existing?.assertionRules ?? [],
+            "Assertion"
+        ),
+        timeoutPolicy,
+        createdAt: existing?.createdAt || now,
+        updatedAt: now,
+    };
+
+    if (!normalized.name) {
+        throw new Error("Template name is required.");
+    }
+    if (!normalized.taskInstruction && !normalized.startUrl) {
+        throw new Error("Template requires taskInstruction or startUrl.");
+    }
+
+    return normalized;
+}
+
+function buildTemplatedInstruction(taskInstruction, template) {
+    if (!template) {
+        return taskInstruction;
+    }
+
+    const parts = [];
+    const baseTaskInstruction = taskInstruction || template.taskInstruction || "";
+    if (baseTaskInstruction) {
+        parts.push(baseTaskInstruction);
+    }
+    if (template.startUrl) {
+        parts.push(`Always start by navigating to this URL: ${template.startUrl}`);
+    }
+    if (template.preLoginChecks?.length) {
+        const checks = template.preLoginChecks
+            .map((rule, index) => `${index + 1}. [${rule.kind}] ${rule.expected} (${rule.name})`)
+            .join("\n");
+        parts.push(
+            `Before executing the main task, verify these login checks and ask_main_agent immediately if any required check fails:\n${checks}`
+        );
+    }
+    if (template.assertionRules?.length) {
+        const assertions = template.assertionRules
+            .map((rule, index) => `${index + 1}. [${rule.kind}] ${rule.expected} (${rule.name})`)
+            .join("\n");
+        parts.push(`Treat the run as complete only when all assertions pass:\n${assertions}`);
+    }
+
+    return parts.filter(Boolean).join("\n\n");
+}
+
+function evaluateRule(rule, page) {
+    const safePage = page || {};
+    const sources = {
+        url_includes: safePage.url || "",
+        title_includes: safePage.title || "",
+        text_includes: safePage.textPreview || "",
+    };
+    const source = String(sources[rule.kind] || "");
+    const passed = source.toLowerCase().includes(String(rule.expected).toLowerCase());
+    return {
+        id: rule.id,
+        name: rule.name,
+        kind: rule.kind,
+        expected: rule.expected,
+        required: rule.required !== false,
+        actual: source.slice(0, 500),
+        passed,
+    };
+}
+
+function evaluateTemplate(template, result) {
+    if (!template) {
+        return null;
+    }
+
+    const page = result?.page || null;
+    const loginChecks = (template.preLoginChecks || []).map((rule) => evaluateRule(rule, page));
+    const assertions = (template.assertionRules || []).map((rule) => evaluateRule(rule, page));
+    const failures = [...loginChecks, ...assertions].filter((item) => item.required && !item.passed);
+
+    return {
+        templateId: template.id,
+        templateName: template.name,
+        evaluatedAt: nowIso(),
+        page: page ? {
+            url: page.url || "",
+            title: page.title || "",
+        } : null,
+        loginChecks,
+        assertions,
+        passed: failures.length === 0,
+        failureMessages: failures.map((item) => `${item.name} (${item.kind}) expected "${item.expected}"`),
+    };
+}
+
+export class TaskRunner {
+    constructor(baseDir, options = {}) {
+        this.runtime = options.runtime || new BrowserRuntime(baseDir);
+        this.subagent = options.subagent || new BrowserSubagent(this.runtime, options.plannerOptions || {});
+        this.store = new TaskRunStore(baseDir);
+        this.templateStore = new RunTemplateStore(baseDir);
+        this.runs = this.store.load();
+        this.templates = this.templateStore.load().filter((template) => typeof template?.id === "string");
+        this.processing = false;
+        this.events = new EventEmitter();
+        this.pendingReplies = new Map();
+        this.runControls = new Map();
+        this.handoffTimeoutMs = options.handoffTimeoutMs || 5 * 60 * 1000;
+        this.runHistoryLimit = Number.isFinite(RUN_HISTORY_LIMIT_ENV) && RUN_HISTORY_LIMIT_ENV > 0
+            ? Math.floor(RUN_HISTORY_LIMIT_ENV)
+            : 200;
+        this.recoverPersistedRuns();
+    }
+
+    trimRunHistory() {
+        const terminalStatuses = new Set(["completed", "failed", "aborted"]);
+        if (!Number.isFinite(this.runHistoryLimit) || this.runHistoryLimit <= 0 || this.runs.length <= this.runHistoryLimit) {
+            return;
+        }
+
+        const activeCount = this.runs.filter((run) => !terminalStatuses.has(run.status)).length;
+        const allowedTerminalCount = Math.max(0, this.runHistoryLimit - activeCount);
+        let keptTerminalCount = 0;
+        const trimmed = [];
+
+        for (const run of this.runs) {
+            if (!terminalStatuses.has(run.status)) {
+                trimmed.push(run);
+                continue;
+            }
+
+            if (keptTerminalCount < allowedTerminalCount) {
+                trimmed.push(run);
+                keptTerminalCount += 1;
+            }
+        }
+
+        this.runs = trimmed;
+    }
+
+    persistRuns() {
+        this.trimRunHistory();
+        this.store.persist(this.runs);
+    }
+
+    recoverPersistedRuns() {
+        const interruptedStatuses = new Set([
+            "running",
+            "aborting",
+            "waiting_for_instruction",
+            "manual_control_requested",
+            "manual_control",
+        ]);
+        let changed = false;
+
+        this.runs = this.runs.filter((run) => typeof run?.id === "string" && run.id.length > 0);
+
+        for (const run of this.runs) {
+            if (interruptedStatuses.has(run.status)) {
+                const interruptionSummary = "Run interrupted because the daemon restarted before completion.";
+                run.status = "failed";
+                run.summary = interruptionSummary;
+                run.pendingInput = null;
+                run.finishedAt = run.finishedAt || nowIso();
+                run.error = run.error || {
+                    message: interruptionSummary,
+                    stack: null,
+                };
+                if (run.result) {
+                    run.result.status = "failed";
+                    run.result.summary = interruptionSummary;
+                    run.result.pendingInput = null;
+                }
+                changed = true;
+            }
+
+            if (run.status === "queued") {
+                this.runControls.set(run.id, {
+                    aborted: false,
+                    reason: null,
+                    manualRequest: null,
+                });
+            }
+        }
+
+        if (changed) {
+            this.trimRunHistory();
+            this.store.persist(this.runs);
+        }
+
+        if (this.runs.some((run) => run.status === "queued")) {
+            void this.processQueue();
+        }
+    }
+
+    createRun(taskInstruction, options = {}) {
+        const templateSnapshot = options.templateSnapshot || null;
+        const resolvedTaskInstruction = typeof taskInstruction === "string" ? taskInstruction.trim() : "";
+        const fallbackTemplateTask = templateSnapshot?.taskInstruction || "";
+        const finalTaskInstruction = resolvedTaskInstruction || fallbackTemplateTask;
+        if (!finalTaskInstruction && !templateSnapshot?.startUrl) {
+            throw new Error("taskInstruction is required when template has no startUrl.");
+        }
+
+        const resolvedMaxSteps = normalizePositiveInteger(
+            options.maxSteps,
+            normalizePositiveInteger(templateSnapshot?.timeoutPolicy?.maxSteps, 12),
+            1
+        );
+        const resolvedHandoffTimeoutMs = normalizePositiveInteger(
+            options.handoffTimeoutMs,
+            normalizePositiveInteger(templateSnapshot?.timeoutPolicy?.handoffTimeoutMs, this.handoffTimeoutMs),
+            1000
+        );
+        const run = {
+            id: crypto.randomUUID(),
+            taskInstruction: finalTaskInstruction,
+            maxSteps: resolvedMaxSteps,
+            browserSource: options.browserSource || "auto",
+            cdpEndpoint: options.cdpEndpoint || null,
+            handoffTimeoutMs: resolvedHandoffTimeoutMs,
+            template: templateSnapshot ? {
+                ...templateSnapshot,
+                timeoutPolicy: {
+                    ...templateSnapshot.timeoutPolicy,
+                    maxSteps: resolvedMaxSteps,
+                    handoffTimeoutMs: resolvedHandoffTimeoutMs,
+                },
+            } : null,
+            status: "queued",
+            createdAt: nowIso(),
+            startedAt: null,
+            finishedAt: null,
+            summary: "",
+            error: null,
+            result: null,
+            artifacts: null,
+            reports: null,
+            pendingInput: null,
+            templateEvaluation: null,
+        };
+
+        this.runs.unshift(run);
+        this.trimRunHistory();
+        this.runControls.set(run.id, {
+            aborted: false,
+            reason: null,
+            manualRequest: null,
+        });
+        this.store.persist(this.runs);
+        this.emitUpdate("run_created", run);
+        void this.processQueue();
+        return run;
+    }
+
+    listTemplates(limit = 100) {
+        return this.templates.slice(0, Math.max(1, limit));
+    }
+
+    getTemplate(id) {
+        return this.templates.find((template) => template.id === id) || null;
+    }
+
+    saveTemplate(templateInput) {
+        const current = typeof templateInput?.id === "string" ? this.getTemplate(templateInput.id) : null;
+        const template = normalizeTemplateInput(templateInput || {}, current);
+        const existingIndex = this.templates.findIndex((item) => item.id === template.id);
+        if (existingIndex >= 0) {
+            this.templates[existingIndex] = template;
+        } else {
+            this.templates.unshift(template);
+        }
+        this.templateStore.persist(this.templates);
+        this.emitUpdate("template_saved", null);
+        return template;
+    }
+
+    deleteTemplate(id) {
+        const existing = this.getTemplate(id);
+        if (!existing) {
+            throw new Error(`Template not found: ${id}`);
+        }
+        this.templates = this.templates.filter((template) => template.id !== id);
+        this.templateStore.persist(this.templates);
+        this.emitUpdate("template_deleted", null);
+        return existing;
+    }
+
+    createRunFromTemplate(templateId, overrides = {}) {
+        const template = this.getTemplate(templateId);
+        if (!template) {
+            throw new Error(`Template not found: ${templateId}`);
+        }
+
+        return this.createRun(overrides.taskInstruction || template.taskInstruction || "", {
+            maxSteps: normalizePositiveInteger(overrides.maxSteps, template.timeoutPolicy?.maxSteps, 1),
+            browserSource: overrides.browserSource || template.browserSource || "auto",
+            cdpEndpoint: overrides.cdpEndpoint || template.cdpEndpoint || null,
+            handoffTimeoutMs: normalizePositiveInteger(overrides.handoffTimeoutMs, template.timeoutPolicy?.handoffTimeoutMs, 1000),
+            templateSnapshot: template,
+        });
+    }
+
+    compareTemplateRuns(templateId, options = {}) {
+        const limit = normalizePositiveInteger(options.limit, 8, 1);
+        const runs = this.runs
+            .filter((run) => run.template?.id === templateId)
+            .slice(0, limit);
+
+        const comparisons = [];
+        for (let index = 0; index < runs.length - 1; index += 1) {
+            const current = runs[index];
+            const previous = runs[index + 1];
+            const currentPassed = current.templateEvaluation?.passed ?? null;
+            const previousPassed = previous.templateEvaluation?.passed ?? null;
+            comparisons.push({
+                currentRunId: current.id,
+                previousRunId: previous.id,
+                statusChanged: current.status !== previous.status,
+                assertionPassedChanged: currentPassed !== previousPassed,
+                summaryChanged: current.summary !== previous.summary,
+                currentDurationSeconds: current.startedAt && current.finishedAt
+                    ? Math.max(0, Math.round((new Date(current.finishedAt).getTime() - new Date(current.startedAt).getTime()) / 1000))
+                    : null,
+                previousDurationSeconds: previous.startedAt && previous.finishedAt
+                    ? Math.max(0, Math.round((new Date(previous.finishedAt).getTime() - new Date(previous.startedAt).getTime()) / 1000))
+                    : null,
+            });
+        }
+
+        return {
+            template: this.getTemplate(templateId),
+            runs,
+            comparisons,
+        };
+    }
+
+    listRuns(limit = 20) {
+        return this.runs.slice(0, limit);
+    }
+
+    getRun(id) {
+        return this.runs.find((run) => run.id === id) || null;
+    }
+
+    getRunControl(id) {
+        if (!this.runControls.has(id)) {
+            this.runControls.set(id, {
+                aborted: false,
+                reason: null,
+                manualRequest: null,
+            });
+        }
+        return this.runControls.get(id);
+    }
+
+    replyToRun(id, instruction) {
+        return this.resumeRun(id, instruction);
+    }
+
+    async resumeRun(id, instruction = "Manual control complete. Continue from the current page.") {
+        const run = this.getRun(id);
+        if (!run) {
+            throw new Error(`Run not found: ${id}`);
+        }
+
+        if (!["waiting_for_instruction", "manual_control"].includes(run.status) || !run.pendingInput) {
+            throw new Error(`Run ${id} is not waiting for a resume instruction.`);
+        }
+
+        const resolver = this.pendingReplies.get(id);
+        if (!resolver) {
+            throw new Error(`Run ${id} does not have a pending reply channel.`);
+        }
+
+        const wasManualControl = run.status === "manual_control" || run.pendingInput?.mode === "manual_control";
+        const resolvedInput = {
+            ...run.pendingInput,
+            response: instruction,
+            respondedAt: nowIso(),
+        };
+        if (wasManualControl) {
+            await this.runtime.exitManualControl();
+        }
+        run.summary = "Instruction received. Resuming browser task.";
+        run.status = "running";
+        run.pendingInput = null;
+        if (run.result) {
+            run.result.status = "running";
+            run.result.summary = run.summary;
+            run.result.pendingInput = null;
+        }
+
+        this.store.persist(this.runs);
+        this.emitUpdate("run_resumed", run);
+        clearTimeout(resolver.timeoutId);
+        this.pendingReplies.delete(id);
+        resolver.resolve({
+            instruction,
+            respondedAt: resolvedInput.respondedAt,
+        });
+
+        return run;
+    }
+
+    async requestManualControl(id, reason = "Manual control requested by operator.") {
+        const run = this.getRun(id);
+        if (!run) {
+            throw new Error(`Run not found: ${id}`);
+        }
+
+        if (["completed", "failed", "aborted"].includes(run.status)) {
+            throw new Error(`Run ${id} is already finished.`);
+        }
+
+        if (run.status === "queued") {
+            throw new Error(`Run ${id} has not started yet, so manual control is not available.`);
+        }
+
+        const control = this.getRunControl(id);
+        const pendingInput = {
+            step: run.result?.step || 0,
+            mode: "manual_control",
+            question: "Manual control is active. Use the live session controls, then resume when you are ready.",
+            details: `${reason} Use the daemon endpoints like /observe, /click, /type, /keypress, and /scroll against the same live browser session.`,
+            suggestedReply: "Manual control complete. Continue from the current page.",
+        };
+
+        this.runtime.recordEvent("task_runner_manual_control_requested", {
+            runId: id,
+            reason,
+        });
+
+        if (run.status === "waiting_for_instruction") {
+            await this.runtime.enterManualControl();
+
+            const resolver = this.pendingReplies.get(id);
+            if (resolver?.timeoutId) {
+                clearTimeout(resolver.timeoutId);
+                resolver.timeoutId = null;
+            }
+            if (resolver) {
+                resolver.mode = "manual_control";
+            }
+
+            run.status = "manual_control";
+            run.summary = pendingInput.question;
+            run.pendingInput = pendingInput;
+            if (run.result) {
+                run.result.status = "manual_control";
+                run.result.summary = pendingInput.question;
+                run.result.pendingInput = pendingInput;
+            }
+            this.store.persist(this.runs);
+            this.emitUpdate("run_manual_control", run);
+            return run;
+        }
+
+        if (run.status === "manual_control") {
+            return run;
+        }
+
+        control.manualRequest = {
+            ...pendingInput,
+            requestedAt: nowIso(),
+        };
+        run.status = "manual_control_requested";
+        run.summary = "Manual control requested. Waiting for the next safe pause.";
+        this.store.persist(this.runs);
+        this.emitUpdate("run_manual_control_requested", run);
+        return run;
+    }
+
+    abortRun(id, reason = "Run aborted by operator.") {
+        const run = this.getRun(id);
+        if (!run) {
+            throw new Error(`Run not found: ${id}`);
+        }
+
+        if (["completed", "failed", "aborted"].includes(run.status)) {
+            throw new Error(`Run ${id} is already finished.`);
+        }
+
+        const control = this.getRunControl(id);
+        control.aborted = true;
+        control.reason = reason;
+        this.runtime.recordEvent("task_runner_abort_requested", {
+            runId: id,
+            reason,
+        });
+
+        if (run.status === "queued") {
+            run.status = "aborted";
+            run.summary = reason;
+            run.finishedAt = nowIso();
+            run.pendingInput = null;
+            run.error = null;
+            this.runControls.delete(id);
+            this.trimRunHistory();
+            this.store.persist(this.runs);
+            this.emitUpdate("run_aborted", run);
+            return run;
+        }
+
+        run.status = "aborting";
+        run.summary = reason;
+        this.store.persist(this.runs);
+        this.emitUpdate("run_aborting", run);
+
+        const pendingReply = this.pendingReplies.get(id);
+        if (pendingReply) {
+            clearTimeout(pendingReply.timeoutId);
+            this.pendingReplies.delete(id);
+            pendingReply.resolve({
+                abort: true,
+                reason,
+            });
+        }
+
+        return run;
+    }
+
+    subscribe(listener) {
+        this.events.on("update", listener);
+        return () => this.events.off("update", listener);
+    }
+
+    emitUpdate(type, run) {
+        this.events.emit("update", {
+            type,
+            runId: run?.id || null,
+            timestamp: nowIso(),
+        });
+    }
+
+    async processQueue() {
+        if (this.processing) return;
+        this.processing = true;
+
+        try {
+            while (true) {
+                const nextRun = this.runs.find((run) => run.status === "queued");
+                if (!nextRun) break;
+                await this.executeRun(nextRun);
+            }
+        } finally {
+            this.processing = false;
+        }
+    }
+
+    async executeRun(run) {
+        run.status = "running";
+        run.startedAt = nowIso();
+        run.summary = "Starting browser task...";
+        run.result = {
+            status: "running",
+            step: 0,
+            summary: run.summary,
+            history: [],
+            artifacts: null,
+            page: null,
+            verification: null,
+            operatorMessages: [],
+            pendingInput: null,
+            debug: null,
+            templateEvaluation: null,
+        };
+        this.store.persist(this.runs);
+        this.emitUpdate("run_started", run);
+
+        try {
+            const effectiveTaskInstruction = buildTemplatedInstruction(run.taskInstruction, run.template);
+            const runHandoffTimeoutMs = normalizePositiveInteger(run.handoffTimeoutMs, this.handoffTimeoutMs, 1000);
+            const result = await this.subagent.delegateTask(effectiveTaskInstruction, {
+                maxSteps: run.maxSteps,
+                startOptions: {
+                    source: run.browserSource,
+                    cdpEndpoint: run.cdpEndpoint || undefined,
+                },
+                onProgress: async (progress) => {
+                    run.summary = progress.summary || run.summary;
+                    if (!["aborting", "aborted"].includes(run.status)) {
+                        if (["waiting_for_instruction", "manual_control", "manual_control_requested"].includes(progress.status)) {
+                            run.status = progress.status;
+                        }
+                    }
+                    run.result = progress;
+                    run.artifacts = progress.artifacts || run.artifacts;
+                    run.pendingInput = progress.pendingInput || null;
+                    this.store.persist(this.runs);
+                    this.emitUpdate("run_updated", run);
+                },
+                onNeedsInput: async (pendingInput) => {
+                    const waitingStatus = pendingInput.mode === "manual_control" ? "manual_control" : "waiting_for_instruction";
+                    if (pendingInput.mode === "manual_control") {
+                        await this.runtime.enterManualControl();
+                    }
+                    run.status = waitingStatus;
+                    run.pendingInput = {
+                        ...pendingInput,
+                        requestedAt: nowIso(),
+                    };
+                    run.summary = pendingInput.question || "Waiting for instruction.";
+                    if (run.result) {
+                        run.result.status = waitingStatus;
+                        run.result.pendingInput = run.pendingInput;
+                    }
+                    this.store.persist(this.runs);
+                    this.emitUpdate(waitingStatus === "manual_control" ? "run_manual_control" : "run_waiting", run);
+
+                    return await new Promise((resolve) => {
+                        let timeoutId = null;
+                        if (pendingInput.mode !== "manual_control") {
+                            timeoutId = setTimeout(() => {
+                                this.pendingReplies.delete(run.id);
+                                const timeoutReason = `Timed out waiting for instruction after ${formatTimeoutDuration(runHandoffTimeoutMs)}.`;
+                                const control = this.getRunControl(run.id);
+                                control.aborted = true;
+                                control.reason = timeoutReason;
+                                resolve({
+                                    abort: true,
+                                    reason: timeoutReason,
+                                });
+                            }, runHandoffTimeoutMs);
+                        }
+
+                        this.pendingReplies.set(run.id, {
+                            resolve,
+                            timeoutId,
+                            mode: pendingInput.mode || "guidance",
+                        });
+                    });
+                },
+                shouldAbort: () => this.getRunControl(run.id).aborted,
+                getAbortReason: () => this.getRunControl(run.id).reason || "Browser task aborted.",
+                pullHandoffRequest: () => {
+                    const control = this.getRunControl(run.id);
+                    const request = control.manualRequest;
+                    control.manualRequest = null;
+                    return request;
+                },
+            });
+
+            const templateEvaluation = evaluateTemplate(run.template, result);
+            if (templateEvaluation) {
+                result.templateEvaluation = templateEvaluation;
+                run.templateEvaluation = templateEvaluation;
+                if (!templateEvaluation.passed) {
+                    result.status = "failed";
+                    const firstFailure = templateEvaluation.failureMessages[0] || "Template checks failed.";
+                    result.summary = `Template checks failed: ${firstFailure}`;
+                }
+            }
+
+            run.status = result.status === "completed" ? "completed" : result.status === "aborted" ? "aborted" : "failed";
+            run.summary = result.summary;
+            run.result = result;
+            run.artifacts = result.artifacts;
+            run.reports = result.reports;
+            run.pendingInput = result.pendingInput || null;
+            run.error = null;
+            this.emitUpdate("run_updated", run);
+        } catch (error) {
+            run.status = "failed";
+            run.summary = error.message;
+            run.error = {
+                message: error.message,
+                stack: error.stack || null,
+            };
+            this.emitUpdate("run_updated", run);
+        } finally {
+            const stopResult = await this.runtime.stop().catch(() => null);
+            if (stopResult?.artifacts) {
+                run.artifacts = stopResult.artifacts;
+                if (run.result) {
+                    run.result.artifacts = stopResult.artifacts;
+                    try {
+                        const refreshedReports = this.subagent.writeReports(run.result);
+                        run.result.reports = refreshedReports;
+                        run.reports = refreshedReports;
+                    } catch (error) {
+                        // Keep original reports if post-stop refresh fails.
+                    }
+                }
+            }
+            run.finishedAt = nowIso();
+            const pendingReply = this.pendingReplies.get(run.id);
+            if (pendingReply) {
+                clearTimeout(pendingReply.timeoutId);
+                this.pendingReplies.delete(run.id);
+            }
+            this.runControls.delete(run.id);
+            this.trimRunHistory();
+            this.store.persist(this.runs);
+            this.emitUpdate("run_finished", run);
+        }
+    }
+}