@steipete/oracle 0.15.0 → 0.15.2

package/dist/src/browser/chatgptFiles.js

@@ -1,10 +1,134 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { ASSISTANT_ROLE_SELECTOR, CONVERSATION_TURN_SELECTOR } from "./constants.js";
-import { resolveSessionArtifactsDir, writeBinaryBrowserArtifact } from "./artifacts.js";
+import { ASSISTANT_ROLE_SELECTOR } from "./constants.js";
+import { buildConversationTurnListExpression } from "./conversationTurns.js";
+import { computeFileSha256, resolveSessionArtifactsDir, sanitizeArtifactFilename, validateArtifactFile, writeBinaryBrowserArtifact, } from "./artifacts.js";
 const CHATGPT_DOWNLOAD_BASE_URL = "https://chatgpt.com/";
 const DOWNLOAD_BUTTON_WAIT_MS = 15_000;
 const DOWNLOAD_REDIRECT_LIMIT = 5;
+const DIAGNOSTIC_BODY_SNIPPET_BYTES = 180;
+class ChatGptDownloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChatGptDownloadError";
+    }
+}
+function safeDiagnosticText(value, maxLength = DIAGNOSTIC_BODY_SNIPPET_BYTES) {
+    const compact = value
+        .replace(/https?:\/\/[^\s"'<>]+/gi, (match) => {
+        try {
+            const url = new URL(match);
+            return `${url.origin}${url.pathname}${url.search ? "?[redacted]" : ""}`;
+        }
+        catch {
+            return "[redacted-url]";
+        }
+    })
+        .replace(/("?(?:access_token|authorization|bearer|cookie|id_token|key|secret|session|signature|sig|token)"?\s*[:=]\s*)"?[^,"'\s}]+"?/gi, "$1[redacted]")
+        .replace(/\b(access[_ -]?token|authorization|bearer|cookie|id[_ -]?token|api[_ -]?key|secret|session|signature|sig|token)\b\s+["']?[a-z0-9._~+/=-]{4,}/gi, "$1 [redacted]")
+        .replace(/[\r\n\t]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return compact.length > maxLength ? `${compact.slice(0, maxLength)}…` : compact;
+}
+function classifyResponseBodyKind(contentType) {
+    const value = String(contentType ?? "").toLowerCase();
+    if (value.includes("json"))
+        return "json";
+    if (value.includes("html"))
+        return "html";
+    if (value.startsWith("text/") || value.includes("xml"))
+        return "text";
+    return "binary";
+}
+function decodeDiagnosticBodySnippet(body, contentType) {
+    const bodyKind = classifyResponseBodyKind(contentType);
+    if (body.length === 0 || bodyKind === "binary") {
+        return { bodyKind };
+    }
+    let text = body.subarray(0, DIAGNOSTIC_BODY_SNIPPET_BYTES * 4).toString("utf8");
+    if (bodyKind === "html") {
+        text = text.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ").replace(/<[^>]+>/g, " ");
+    }
+    return { bodyKind, bodySnippet: safeDiagnosticText(text) };
+}
+async function readDiagnosticResponseBody(response, contentType) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return { bodyKind: classifyResponseBodyKind(contentType) };
+    }
+    const limit = DIAGNOSTIC_BODY_SNIPPET_BYTES * 4;
+    const chunks = [];
+    let total = 0;
+    try {
+        while (total < limit) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const remaining = limit - total;
+            const chunk = Buffer.from(value.subarray(0, remaining));
+            chunks.push(chunk);
+            total += chunk.length;
+            if (total >= limit) {
+                await reader.cancel().catch(() => undefined);
+                break;
+            }
+        }
+        return decodeDiagnosticBodySnippet(Buffer.concat(chunks), contentType);
+    }
+    catch {
+        return { bodyKind: classifyResponseBodyKind(contentType) };
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function classifyUrlKind(value) {
+    const raw = String(value ?? "");
+    if (!raw)
+        return "unknown";
+    if (raw.startsWith("sandbox:"))
+        return "sandbox";
+    if (raw === "browser-download")
+        return "browser-download";
+    try {
+        const url = new URL(raw, CHATGPT_DOWNLOAD_BASE_URL);
+        if (!isAllowedChatGptHost(url.hostname))
+            return "external-https";
+        const pathName = url.pathname.toLowerCase();
+        if (pathName === "/backend-api/sandbox/download")
+            return "chatgpt-sandbox-download";
+        if (/^\/backend-api\/files\/[^/]+\/(?:download|content)\/?$/.test(pathName)) {
+            return "chatgpt-file-endpoint";
+        }
+        if (pathName === "/backend-api/estuary/content")
+            return "chatgpt-estuary-content";
+        return "chatgpt-other";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function formatDownloadFailure(params) {
+    const parts = [`download failed via ${params.strategy}`];
+    if (params.status !== undefined)
+        parts.push(`status=${params.status}`);
+    if (params.statusText)
+        parts.push(`statusText=${safeDiagnosticText(params.statusText, 80)}`);
+    if (params.contentType)
+        parts.push(`contentType=${safeDiagnosticText(params.contentType, 80)}`);
+    parts.push(`finalUrlKind=${classifyUrlKind(params.finalUrl)}`);
+    if (params.bodyKind)
+        parts.push(`bodyKind=${params.bodyKind}`);
+    if (params.bodySnippet)
+        parts.push(`bodySnippet=${JSON.stringify(params.bodySnippet)}`);
+    if (params.message)
+        parts.push(`reason=${safeDiagnosticText(params.message, 140)}`);
+    return new ChatGptDownloadError(parts.join(" "));
+}
+function sanitizeCandidateFilename(value) {
+    return sanitizeArtifactFilename(String(value ?? ""), "artifact.bin");
+}
 function isAllowedChatGptHost(hostname) {
     const value = hostname.toLowerCase();
     return value === "chatgpt.com" || value === "chat.openai.com";
@@ -149,11 +273,9 @@ function buildAssistantDownloadableFilesExpression(minTurnIndex) {
     const minTurnLiteral = typeof minTurnIndex === "number" && Number.isFinite(minTurnIndex) && minTurnIndex >= 0
         ? Math.floor(minTurnIndex)
         : -1;
-    const conversationLiteral = JSON.stringify(CONVERSATION_TURN_SELECTOR);
     const assistantLiteral = JSON.stringify(ASSISTANT_ROLE_SELECTOR);
     return `(() => {
     const MIN_TURN_INDEX = ${minTurnLiteral};
-    const CONVERSATION_SELECTOR = ${conversationLiteral};
     const ASSISTANT_SELECTOR = ${assistantLiteral};
     const isAssistantTurn = (node) => {
       if (!(node instanceof HTMLElement)) return false;
@@ -210,36 +332,59 @@ function buildAssistantDownloadableFilesExpression(minTurnIndex) {
         return part;
       }
     };
-    const serializeAnchor = (anchor) => {
-      const hrefAttr = anchor.getAttribute('href') || '';
-      const values = [hrefAttr, anchor.href || ''];
-      for (const attribute of Array.from(anchor.attributes || [])) {
+    const hrefKind = (value) => {
+      if (!value) return '';
+      if (isSandboxUrl(value)) return 'sandbox';
+      if (isChatGptDownloadUrl(value)) return 'chatgpt-file-endpoint';
+      return '';
+    };
+    const collectValues = (node) => {
+      const values = [];
+      if (String(node.tagName || '').toLowerCase() === 'a') {
+        values.push(node.getAttribute('href') || '', node.href || '', node.getAttribute('download') || '');
+      }
+      for (const attribute of Array.from(node.attributes || [])) {
         values.push(String(attribute.value || ''));
       }
+      for (const anchor of Array.from(node.querySelectorAll?.('a[href], a[download]') || [])) {
+        values.push(anchor.getAttribute('href') || '', anchor.href || '', anchor.getAttribute('download') || '');
+        for (const attribute of Array.from(anchor.attributes || [])) {
+          values.push(String(attribute.value || ''));
+        }
+      }
+      return values;
+    };
+    const serializeCandidate = (node) => {
+      if (!(node instanceof HTMLElement)) return null;
+      const values = collectValues(node);
       const downloadUrl = values.find(isChatGptDownloadUrl) || '';
       const sandboxUrl = values.find(isSandboxUrl) || '';
       if (!downloadUrl && !sandboxUrl) return null;
-      const label = (anchor.textContent || anchor.getAttribute('aria-label') || anchor.title || '').trim();
-      const filename =
-        anchor.getAttribute('download') ||
-        basename(sandboxUrl) ||
-        basename(downloadUrl) ||
-        label ||
-        '';
+      const label = (node.textContent || node.getAttribute('aria-label') || node.getAttribute('title') || '').trim();
+      const downloadAttr = String(node.tagName || '').toLowerCase() === 'a' ? node.getAttribute('download') || '' : '';
+      const filename = downloadAttr || basename(sandboxUrl) || basename(downloadUrl) || label || '';
       return {
-        url: downloadUrl || sandboxUrl || hrefAttr || anchor.href || '',
+        url: downloadUrl || sandboxUrl || values.find(hrefKind) || '',
         downloadUrl,
         sandboxUrl,
         filename,
         label,
-        mimeType: anchor.getAttribute('type') || '',
+        mimeType: node.getAttribute('type') || '',
       };
     };
     const serializeFiles = (root) =>
-      Array.from(root.querySelectorAll('a[href], a[download]'))
-        .map(serializeAnchor)
+      Array.from(root.querySelectorAll([
+        'a[href]',
+        'a[download]',
+        'button',
+        '[role="button"]',
+        '[data-testid]',
+        '[aria-label]',
+        '[title]',
+      ].join(',')))
+        .map(serializeCandidate)
         .filter(Boolean);
-    const turns = Array.from(document.querySelectorAll(CONVERSATION_SELECTOR));
+    const turns = ${buildConversationTurnListExpression()};
     const files = [];
     for (let index = turns.length - 1; index >= 0; index -= 1) {
       const turn = turns[index];
@@ -296,6 +441,23 @@ function filenameFromContentDisposition(value) {
     }
     return /filename="?([^";]+)"?/i.exec(header)?.[1]?.trim();
 }
+function classifyDownloadableFileSourceKind(file, downloadUrl) {
+    if (file.sandboxUrl || file.url.startsWith("sandbox:")) {
+        return "sandbox";
+    }
+    if ((downloadUrl ?? file.downloadUrl ?? file.url) === "browser-download") {
+        return "browser-download";
+    }
+    return "chatgpt-file-endpoint";
+}
+function describeDownloadableCandidate(file, downloadUrl) {
+    const filename = sanitizeCandidateFilename(file.filename ??
+        file.label ??
+        filenameFromUrl(file.sandboxUrl) ??
+        filenameFromUrl(file.downloadUrl) ??
+        filenameFromUrl(file.url));
+    return `filename=${filename} source=${classifyDownloadableFileSourceKind(file, downloadUrl)} urlKind=${classifyUrlKind(downloadUrl ?? file.downloadUrl ?? file.sandboxUrl ?? file.url)}`;
+}
 function filenameFromUrl(value) {
     const raw = String(value ?? "")
         .split(/[?#]/)[0]
@@ -432,6 +594,7 @@ async function configureBrowserDownloadPath(params) {
             await params.Client.send("Browser.setDownloadBehavior", {
                 behavior: "allow",
                 downloadPath: params.downloadPath,
+                eventsEnabled: true,
             });
             return true;
         }
@@ -462,11 +625,11 @@ function buildClickAssistantDownloadButtonsExpression(minTurnIndex, expectedLabe
     const minTurnLiteral = typeof minTurnIndex === "number" && Number.isFinite(minTurnIndex) && minTurnIndex >= 0
         ? Math.floor(minTurnIndex)
         : -1;
-    const conversationLiteral = JSON.stringify(CONVERSATION_TURN_SELECTOR);
     const assistantLiteral = JSON.stringify(ASSISTANT_ROLE_SELECTOR);
     const expectedLabelsLiteral = JSON.stringify(expectedLabels);
     const allowGenericDownloadLabelsLiteral = JSON.stringify(allowGenericDownloadLabels);
     const markClickedLiteral = JSON.stringify(options.markClicked === true);
+    const returnDiagnosticsLiteral = JSON.stringify(options.returnDiagnostics === true);
     const maxClicksLiteral = typeof options.maxClicks === "number" &&
         Number.isFinite(options.maxClicks) &&
         options.maxClicks > 0
@@ -474,11 +637,11 @@ function buildClickAssistantDownloadButtonsExpression(minTurnIndex, expectedLabe
         : 0;
     return `(() => {
     const MIN_TURN_INDEX = ${minTurnLiteral};
-    const CONVERSATION_SELECTOR = ${conversationLiteral};
     const ASSISTANT_SELECTOR = ${assistantLiteral};
     const EXPECTED_LABELS = ${expectedLabelsLiteral};
     const ALLOW_GENERIC_DOWNLOAD_LABELS = ${allowGenericDownloadLabelsLiteral};
     const MARK_CLICKED = ${markClickedLiteral};
+    const RETURN_DIAGNOSTICS = ${returnDiagnosticsLiteral};
     const MAX_CLICKS = ${maxClicksLiteral};
     const HAS_EXPECTED_LABELS = EXPECTED_LABELS.length > 0;
     const CLICKED_ATTRIBUTE = 'data-oracle-download-clicked';
@@ -492,55 +655,152 @@ function buildClickAssistantDownloadButtonsExpression(minTurnIndex, expectedLabe
       if (testId.includes('assistant')) return true;
       return Boolean(node.querySelector(ASSISTANT_SELECTOR) || node.querySelector('[data-testid*="assistant"]'));
     };
-    const expectedFileButton = (button) => {
-      const text = (button.textContent || '').trim().toLowerCase();
-      return EXPECTED_LABELS.some((label) => {
-        const downloadLabel = 'download ' + label;
-        return text === label ||
-          text.startsWith(label + ' ') ||
-          text === downloadLabel ||
-          text.startsWith(downloadLabel + ' ');
-      });
+    const basename = (value) => {
+      const raw = String(value || '').split(/[?#]/)[0].replace(/\\/+$/g, '');
+      const part = raw.slice(raw.lastIndexOf('/') + 1);
+      try {
+        return decodeURIComponent(part);
+      } catch {
+        return part;
+      }
     };
-    const genericBehaviorButton = (button) => {
-      const text = (button.textContent || '').trim().toLowerCase();
-      return ALLOW_GENERIC_DOWNLOAD_LABELS && /^download\\b/.test(text);
+    const isSafeSandboxUrl = (value) => {
+      const raw = String(value || '').trim();
+      if (!raw.startsWith('sandbox:/mnt/data/')) return false;
+      try {
+        const pathName = decodeURI(new URL(raw).pathname);
+        return pathName.startsWith('/mnt/data/') &&
+          !pathName.includes('\\\\') &&
+          !pathName.includes('\\0') &&
+          !pathName.split('/').includes('..');
+      } catch {
+        return false;
+      }
     };
-    const genericFallbackButton = (button) => {
-      if (!ALLOW_GENERIC_DOWNLOAD_LABELS) return false;
-      const text = (button.textContent || '').trim().toLowerCase();
-      const aria = (button.getAttribute('aria-label') || '').trim().toLowerCase();
-      const testId = (button.getAttribute('data-testid') || '').trim().toLowerCase();
-      return text === 'download' || aria === 'download' || testId === 'download-files-turn-action-button';
+    const isChatGptDownloadUrl = (value) => {
+      const raw = String(value || '').trim();
+      if (!raw || raw.startsWith('sandbox:') || raw.startsWith('blob:')) return false;
+      const isSafeSandboxPath = (pathName) => {
+        const normalized = String(pathName || '');
+        return normalized.startsWith('/mnt/data/') &&
+          !normalized.includes('\\\\') &&
+          !normalized.includes('\\0') &&
+          !normalized.split('/').includes('..');
+      };
+      try {
+        const url = new URL(raw, 'https://chatgpt.com');
+        const host = url.hostname.toLowerCase();
+        const allowedHost = host === 'chatgpt.com' || host === 'chat.openai.com';
+        const pathName = url.pathname.toLowerCase();
+        const isKnownFileDownload =
+          (pathName === '/backend-api/sandbox/download' && isSafeSandboxPath(url.searchParams.get('path') || '')) ||
+          /^\\/backend-api\\/files\\/[^/]+\\/(?:download|content)\\/?$/.test(pathName) ||
+          (pathName === '/backend-api/estuary/content' && String(url.searchParams.get('id') || '').startsWith('file_'));
+        return allowedHost && url.protocol === 'https:' && !url.port && isKnownFileDownload;
+      } catch {
+        return false;
+      }
+    };
+    const safeLower = (value) => String(value || '').trim().toLowerCase();
+    const controlInfo = (control) => {
+      const href = String(control.tagName || '').toLowerCase() === 'a' ? (control.getAttribute('href') || control.href || '') : '';
+      const text = (control.textContent || '').trim();
+      const ariaLabel = control.getAttribute('aria-label') || '';
+      const title = control.getAttribute('title') || '';
+      const testId = control.getAttribute('data-testid') || '';
+      const role = control.getAttribute('role') || '';
+      const download = String(control.tagName || '').toLowerCase() === 'a' ? (control.getAttribute('download') || '') : '';
+      const className = String(control.className || '');
+      const attributeValues = Array.from(control.attributes || []).map((attribute) => String(attribute.value || ''));
+      return {
+        control,
+        tagName: control.tagName || '',
+        text,
+        ariaLabel,
+        title,
+        testId,
+        role,
+        href,
+        download,
+        className,
+        attributeValues,
+        haystack: [text, ariaLabel, title, testId, role, href, download, basename(href), ...attributeValues]
+          .map(safeLower)
+          .filter(Boolean),
+      };
     };
-    const turns = Array.from(document.querySelectorAll(CONVERSATION_SELECTOR));
+    const safeClickableControl = (info) =>
+      safeLower(info.tagName) !== 'a' || isSafeSandboxUrl(info.href) || isChatGptDownloadUrl(info.href);
+    const expectedFileControl = (info) => {
+      return EXPECTED_LABELS.some((rawLabel) => {
+        const label = safeLower(rawLabel);
+        if (!label) return false;
+        const downloadLabel = 'download ' + label;
+        return info.haystack.some((value) =>
+          value === label ||
+          value.startsWith(label + ' ') ||
+          value === downloadLabel ||
+          value.startsWith(downloadLabel + ' ') ||
+          value.endsWith('/' + label) ||
+          value.includes('/' + label + '?') ||
+          value.includes('/' + label + '#') ||
+          value.includes('path=%2fmnt%2fdata%2f' + encodeURIComponent(label).toLowerCase()) ||
+          value.includes('sandbox:/mnt/data/' + label)
+        );
+      });
+    };
+    const hasDownloadIntent = (info) =>
+      info.haystack.some((value) =>
+        value === 'download' ||
+        /^download\\b/.test(value) ||
+        value.includes('download') ||
+        value === 'download-files-turn-action-button'
+      );
+    const genericBehaviorButton = (info) =>
+      ALLOW_GENERIC_DOWNLOAD_LABELS && info.className.includes('behavior-btn') && hasDownloadIntent(info);
+    const genericFallbackButton = (info) => ALLOW_GENERIC_DOWNLOAD_LABELS && hasDownloadIntent(info);
+    const turns = ${buildConversationTurnListExpression()};
     const expectedMatches = new Set();
     const genericBehaviorMatches = new Set();
     const genericFallbackMatches = new Set();
     const genericAllMatches = new Set();
+    let inspectedCount = 0;
     for (let index = turns.length - 1; index >= 0; index -= 1) {
       const turn = turns[index];
       if (!isAssistantTurn(turn)) continue;
       if (MIN_TURN_INDEX >= 0 && index < MIN_TURN_INDEX) continue;
       const messageRoot = turn.querySelector(ASSISTANT_SELECTOR) || turn;
-      const buttons = Array.from(messageRoot.querySelectorAll('button'))
-        .filter((button) => !(MARK_CLICKED && button.getAttribute(CLICKED_ATTRIBUTE) === 'true'));
-      const behaviorButtons = buttons.filter((button) =>
-        String(button.className || '').includes('behavior-btn')
-      );
-      behaviorButtons.filter(expectedFileButton).forEach((button) => expectedMatches.add(button));
-      const genericBehavior = behaviorButtons.filter(genericBehaviorButton);
-      genericBehavior.forEach((button) => {
-        genericBehaviorMatches.add(button);
-        genericAllMatches.add(button);
+      const controls = Array.from(messageRoot.querySelectorAll([
+        'button',
+        'a[href]',
+        'a[download]',
+        '[role="button"]',
+      ].join(',')))
+        .filter((control) => control instanceof HTMLElement)
+        .filter((control) => !(MARK_CLICKED && control.getAttribute(CLICKED_ATTRIBUTE) === 'true'))
+        .map(controlInfo)
+        .filter(safeClickableControl);
+      inspectedCount += controls.length;
+      controls.filter(expectedFileControl).forEach((info) => expectedMatches.add(info));
+      const genericBehavior = controls.filter(genericBehaviorButton);
+      genericBehavior.forEach((info) => {
+        genericBehaviorMatches.add(info);
+        genericAllMatches.add(info);
       });
       if (genericBehavior.length === 0) {
-        buttons.filter(genericFallbackButton).forEach((button) => {
-          genericFallbackMatches.add(button);
-          genericAllMatches.add(button);
+        controls.filter(genericFallbackButton).forEach((info) => {
+          genericFallbackMatches.add(info);
+          genericAllMatches.add(info);
         });
       }
     }
+    const selectedCategory = expectedMatches.size > 0
+      ? 'expected-label'
+      : HAS_EXPECTED_LABELS
+        ? genericBehaviorMatches.size > 0
+          ? 'generic-behavior'
+          : 'generic-fallback'
+        : 'generic-all';
     const selected = expectedMatches.size > 0
       ? expectedMatches
       : HAS_EXPECTED_LABELS
@@ -548,16 +808,23 @@ function buildClickAssistantDownloadButtonsExpression(minTurnIndex, expectedLabe
           ? genericBehaviorMatches
           : genericFallbackMatches
         : genericAllMatches;
-    const selectedButtons = Array.from(selected).slice(0, MAX_CLICKS > 0 ? MAX_CLICKS : undefined);
-    selectedButtons.forEach((button) => {
-      if (MARK_CLICKED) button.setAttribute(CLICKED_ATTRIBUTE, 'true');
-      button.click();
+    const selectedControls = Array.from(selected).slice(0, MAX_CLICKS > 0 ? MAX_CLICKS : undefined);
+    selectedControls.forEach((info) => {
+      if (MARK_CLICKED) info.control.setAttribute(CLICKED_ATTRIBUTE, 'true');
+      info.control.click();
     });
-    return selectedButtons.map((button) => ({
-      text: (button.textContent || '').trim(),
-      ariaLabel: button.getAttribute('aria-label') || '',
-      testId: button.getAttribute('data-testid') || '',
+    const clickedDiagnostics = selectedControls.map((info) => ({
+      text: info.text,
+      ariaLabel: info.ariaLabel,
+      title: info.title,
+      testId: info.testId,
+      tagName: info.tagName,
+      role: info.role,
+      hrefKind: info.href ? (info.href.startsWith('sandbox:') ? 'sandbox' : 'link') : '',
+      category: selectedCategory,
     }));
+    const clicked = clickedDiagnostics.map(({ text, ariaLabel, testId }) => ({ text, ariaLabel, testId }));
+    return RETURN_DIAGNOSTICS ? { inspectedCount, selectedCategory, clicked: clickedDiagnostics } : clicked;
   })()`;
 }
 function describeDownloadableFile(file) {
@@ -604,31 +871,112 @@ async function moveDownloadedFileToExpectedName(filePath, file) {
     return targetPath;
 }
 async function clickAssistantDownloadButtons(params) {
-    const expression = buildClickAssistantDownloadButtonsExpression(params.minTurnIndex, params.expectedLabels ?? [], params.allowGenericDownloadLabels, { markClicked: params.markClicked, maxClicks: params.maxClicks });
+    const expression = buildClickAssistantDownloadButtonsExpression(params.minTurnIndex, params.expectedLabels ?? [], params.allowGenericDownloadLabels, { markClicked: params.markClicked, maxClicks: params.maxClicks, returnDiagnostics: true });
     const deadline = Date.now() + (params.timeoutMs ?? DOWNLOAD_BUTTON_WAIT_MS);
+    let lastInspectedCount = 0;
+    let lastSelectedCategory;
     while (Date.now() < deadline) {
         const { result } = await params.Runtime.evaluate({
             expression,
             returnByValue: true,
         });
-        const clicked = Array.isArray(result?.value) ? result.value : [];
+        const value = result?.value;
+        const diagnosticValue = value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+        const clicked = Array.isArray(value)
+            ? value
+            : Array.isArray(diagnosticValue?.clicked)
+                ? diagnosticValue.clicked
+                : [];
+        if (diagnosticValue) {
+            lastInspectedCount = Number(diagnosticValue.inspectedCount ?? lastInspectedCount);
+            lastSelectedCategory = diagnosticValue.selectedCategory ?? lastSelectedCategory;
+        }
         if (clicked.length > 0) {
-            return clicked;
+            return {
+                clicked,
+                inspectedCount: lastInspectedCount,
+                selectedCategory: lastSelectedCategory,
+            };
         }
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
-    return [];
+    return {
+        clicked: [],
+        inspectedCount: lastInspectedCount,
+        selectedCategory: lastSelectedCategory,
+    };
+}
+function summarizeClickedControls(clicked) {
+    return clicked
+        .slice(0, 5)
+        .map((control) => {
+        const tag = control.tagName ? `tag=${safeDiagnosticText(control.tagName, 24)}` : "tag=?";
+        const category = control.category
+            ? `category=${safeDiagnosticText(control.category, 40)}`
+            : "category=?";
+        const testId = control.testId ? ` testId=${safeDiagnosticText(control.testId, 60)}` : "";
+        const aria = control.ariaLabel ? ` aria=${safeDiagnosticText(control.ariaLabel, 60)}` : "";
+        const text = control.text ? ` text=${safeDiagnosticText(control.text, 60)}` : "";
+        const hrefKind = control.hrefKind
+            ? ` hrefKind=${safeDiagnosticText(control.hrefKind, 40)}`
+            : "";
+        return `${tag} ${category}${testId}${aria}${text}${hrefKind}`;
+    })
+        .join("; ");
+}
+async function clickGeneratedDownloadUrl(params) {
+    const filename = expectedDownloadedFilename(params.file) ?? "download";
+    const expression = `(() => {
+    const anchor = document.createElement('a');
+    anchor.href = ${JSON.stringify(params.downloadUrl)};
+    anchor.download = ${JSON.stringify(filename)};
+    anchor.rel = 'noopener';
+    anchor.style.display = 'none';
+    anchor.setAttribute('data-oracle-generated-download-anchor', 'true');
+    document.body.appendChild(anchor);
+    anchor.click();
+    setTimeout(() => anchor.remove(), 0);
+    return {
+      inspectedCount: 1,
+      selectedCategory: 'generated-download-url',
+      clicked: [{
+        text: '',
+        ariaLabel: '',
+        title: '',
+        testId: 'oracle-generated-download-anchor',
+        tagName: 'A',
+        role: '',
+        hrefKind: ${JSON.stringify(classifyUrlKind(params.downloadUrl))},
+        category: 'generated-download-url',
+      }],
+    };
+  })()`;
+    const { result } = await params.Runtime.evaluate({ expression, returnByValue: true });
+    const value = result?.value;
+    return {
+        clicked: Array.isArray(value?.clicked) ? value.clicked : [],
+        inspectedCount: Number(value?.inspectedCount ?? 1),
+        selectedCategory: value?.selectedCategory ?? "generated-download-url",
+    };
 }
 async function savedBrowserFileFromPath(filePath) {
     const filename = path.basename(filePath);
     const stat = await fs.stat(filePath);
+    const mimeType = mimeTypeFromFilename(filename);
+    const validation = await validateArtifactFile({ path: filePath, filename, mimeType });
     return {
         kind: "file",
         path: filePath,
         label: filename,
-        mimeType: mimeTypeFromFilename(filename),
+        mimeType,
         sizeBytes: stat.size,
         sourceUrl: "browser-download",
+        sha256: await computeFileSha256(filePath),
+        validation,
+        transfer: { status: "not-needed" },
+        origin: { mode: "local" },
         url: "browser-download",
         finalUrl: "browser-download",
         filename,
@@ -661,19 +1009,22 @@ export async function saveAssistantDownloadButtonArtifacts(params) {
     const downloadWaitMs = params.downloadWaitMs ?? DOWNLOAD_BUTTON_WAIT_MS;
     const expectedFiles = params.files ?? [];
     if (expectedFiles.length === 0) {
-        const clicked = await clickAssistantDownloadButtons({
+        const clickedResult = await clickAssistantDownloadButtons({
             Runtime: params.Runtime,
             minTurnIndex: params.minTurnIndex,
             expectedLabels: [],
             allowGenericDownloadLabels: params.allowGenericDownloadLabels,
             timeoutMs: buttonWaitMs,
+            logger: params.logger,
         });
-        if (clicked.length === 0) {
-            params.logger?.("[browser] No assistant download buttons found for button fallback.");
+        if (clickedResult.clicked.length === 0) {
+            params.logger?.(`[browser] No assistant download controls found for button fallback (inspected ${clickedResult.inspectedCount} control(s); category=${clickedResult.selectedCategory ?? "none"}).`);
             return [];
         }
-        params.logger?.(`[browser] Clicked ${clicked.length} assistant download button(s).`);
-        const downloaded = await waitForCompletedDownloadFiles(artifactsDir, before, clicked.length, downloadWaitMs);
+        params.logger?.(`[browser] Clicked ${clickedResult.clicked.length} assistant download control(s) ` +
+            `(inspected ${clickedResult.inspectedCount}; category=${clickedResult.selectedCategory ?? "unknown"}; ` +
+            `details=${summarizeClickedControls(clickedResult.clicked)}).`);
+        const downloaded = await waitForCompletedDownloadFiles(artifactsDir, before, clickedResult.clicked.length, downloadWaitMs);
         return Promise.all(downloaded.map(savedBrowserFileFromPath));
     }
     let clickedCount = 0;
@@ -683,7 +1034,8 @@ export async function saveAssistantDownloadButtonArtifacts(params) {
     const unattemptedFiles = [];
     for (const [fileIndex, file] of expectedFiles.entries()) {
         const expectedLabels = resolveDownloadButtonLabels([file]);
-        const clicked = await clickAssistantDownloadButtons({
+        const displayName = describeDownloadableFile(file);
+        let clickResult = await clickAssistantDownloadButtons({
             Runtime: params.Runtime,
             minTurnIndex: params.minTurnIndex,
             expectedLabels,
@@ -691,14 +1043,32 @@ export async function saveAssistantDownloadButtonArtifacts(params) {
             markClicked: true,
             maxClicks: 1,
             timeoutMs: buttonWaitMs,
+            logger: params.logger,
         });
-        const displayName = describeDownloadableFile(file);
-        if (clicked.length === 0) {
+        params.logger?.(`[browser] Button fallback inspected ${clickResult.inspectedCount} control(s) for ${sanitizeCandidateFilename(displayName)}; category=${clickResult.selectedCategory ?? "none"}; clicked=${clickResult.clicked.length}.`);
+        if (clickResult.clicked.length > 0) {
+            params.logger?.(`[browser] Button fallback clicked control detail(s): ${summarizeClickedControls(clickResult.clicked)}`);
+        }
+        else {
+            const explicitDownloadUrl = normalizeChatGptDownloadUrl(file.downloadUrl ?? file.url);
+            const sandboxDownloadUrl = downloadUrlFromSandboxUrl(file.sandboxUrl ?? file.url);
+            const downloadUrl = explicitDownloadUrl ?? sandboxDownloadUrl;
+            if (downloadUrl) {
+                params.logger?.(`[browser] No matching assistant control for ${sanitizeCandidateFilename(displayName)}; trying scoped generated browser download for urlKind=${classifyUrlKind(downloadUrl)}.`);
+                clickResult = await clickGeneratedDownloadUrl({
+                    Runtime: params.Runtime,
+                    file,
+                    downloadUrl,
+                    logger: params.logger,
+                });
+            }
+        }
+        if (clickResult.clicked.length === 0) {
             missingFiles.push(displayName);
             knownEntries = new Set(await fs.readdir(artifactsDir).catch(() => []));
             continue;
         }
-        clickedCount += clicked.length;
+        clickedCount += clickResult.clicked.length;
         const downloaded = await waitForCompletedDownloadFiles(artifactsDir, knownEntries, 1, downloadWaitMs);
         if (downloaded.length === 0) {
             missingFiles.push(displayName);
@@ -714,10 +1084,10 @@ export async function saveAssistantDownloadButtonArtifacts(params) {
         knownEntries = new Set(await fs.readdir(artifactsDir).catch(() => []));
     }
     if (clickedCount === 0) {
-        params.logger?.("[browser] No assistant download buttons found for button fallback.");
+        params.logger?.("[browser] No assistant download controls found for button fallback.");
     }
     else {
-        params.logger?.(`[browser] Clicked ${clickedCount} assistant download button(s).`);
+        params.logger?.(`[browser] Clicked ${clickedCount} assistant download control(s).`);
     }
     if (missingFiles.length > 0) {
         params.logger?.(`[browser] Download button fallback did not save expected file(s): ${missingFiles.join(", ")}`);
@@ -734,7 +1104,11 @@ async function fetchDownloadWithNode(downloadUrl, getCookieHeader) {
             isKnownChatGptFileDownloadUrl(currentUrl)) {
             const cookieHeader = await getCookieHeader(currentUrl.href);
             if (!cookieHeader) {
-                throw new Error("Missing ChatGPT cookies for file download.");
+                throw formatDownloadFailure({
+                    strategy: "node-fetch",
+                    finalUrl: currentUrl.href,
+                    message: "missing ChatGPT cookies for file download",
+                });
             }
             headers.cookie = cookieHeader;
         }
@@ -742,29 +1116,58 @@ async function fetchDownloadWithNode(downloadUrl, getCookieHeader) {
             headers,
             redirect: "manual",
         });
+        const contentType = response.headers.get("content-type");
         if (response.status >= 300 && response.status < 400) {
             const location = response.headers.get("location");
             if (!location) {
-                throw new Error(`download redirect missing location: ${response.status}`);
+                const body = await readDiagnosticResponseBody(response, contentType);
+                throw formatDownloadFailure({
+                    strategy: "node-fetch",
+                    status: response.status,
+                    statusText: response.statusText,
+                    contentType,
+                    finalUrl: currentUrl.href,
+                    ...body,
+                    message: "download redirect missing location",
+                });
             }
             const redirectedUrl = new URL(location, currentUrl);
             if (redirectedUrl.protocol !== "https:") {
-                throw new Error(`download redirect rejected: ${redirectedUrl.protocol}`);
+                throw formatDownloadFailure({
+                    strategy: "node-fetch",
+                    status: response.status,
+                    statusText: response.statusText,
+                    contentType,
+                    finalUrl: redirectedUrl.href,
+                    message: `download redirect rejected: ${redirectedUrl.protocol}`,
+                });
             }
             currentUrl = redirectedUrl;
             continue;
         }
         if (!response.ok) {
-            throw new Error(`download failed: ${response.status} ${response.statusText}`);
+            const body = await readDiagnosticResponseBody(response, contentType);
+            throw formatDownloadFailure({
+                strategy: "node-fetch",
+                status: response.status,
+                statusText: response.statusText,
+                contentType,
+                finalUrl: response.url || currentUrl.href,
+                ...body,
+            });
         }
         return {
             buffer: Buffer.from(await response.arrayBuffer()),
             contentDisposition: response.headers.get("content-disposition"),
-            contentType: response.headers.get("content-type"),
-            finalUrl: response.url,
+            contentType,
+            finalUrl: response.url || currentUrl.href,
         };
     }
-    throw new Error(`download exceeded ${DOWNLOAD_REDIRECT_LIMIT} redirects`);
+    throw formatDownloadFailure({
+        strategy: "node-fetch",
+        finalUrl: currentUrl.href,
+        message: `download exceeded ${DOWNLOAD_REDIRECT_LIMIT} redirects`,
+    });
 }
 async function fetchDownloadWithBrowser(Runtime, downloadUrl) {
     const expression = `(() => {
@@ -799,14 +1202,24 @@ async function fetchDownloadWithBrowser(Runtime, downloadUrl) {
     if (!value) {
         throw new Error("browser download returned no value");
     }
+    const contentType = typeof value.contentType === "string" ? value.contentType : null;
+    const finalUrl = typeof value.url === "string" ? value.url : downloadUrl;
     if (!value.ok) {
-        throw new Error(`download failed: ${value.status ?? "?"} ${value.statusText ?? ""}`.trim());
+        const body = decodeDiagnosticBodySnippet(Buffer.from(String(value.base64 ?? ""), "base64"), contentType);
+        throw formatDownloadFailure({
+            strategy: "browser-fetch",
+            status: value.status,
+            statusText: value.statusText,
+            contentType,
+            finalUrl,
+            ...body,
+        });
     }
     return {
         buffer: Buffer.from(String(value.base64 ?? ""), "base64"),
         contentDisposition: typeof value.contentDisposition === "string" ? value.contentDisposition : null,
-        contentType: typeof value.contentType === "string" ? value.contentType : null,
-        finalUrl: typeof value.url === "string" ? value.url : downloadUrl,
+        contentType,
+        finalUrl,
     };
 }
 export async function saveChatGptDownloadableFiles(params) {
@@ -834,13 +1247,17 @@ export async function saveChatGptDownloadableFiles(params) {
         const sandboxDownloadUrl = downloadUrlFromSandboxUrl(file.sandboxUrl ?? file.url);
         const downloadUrl = explicitDownloadUrl ?? sandboxDownloadUrl;
         if (!downloadUrl) {
-            const source = file.sandboxUrl ?? file.filename ?? file.url;
-            errors.push(`${source}: no ChatGPT download URL found`);
+            const source = sanitizeCandidateFilename(file.sandboxUrl ?? file.filename ?? file.url);
+            const message = `${source}: no ChatGPT download URL found`;
+            errors.push(message);
             failedFiles.push(file);
+            logger?.(`[browser] Skipping downloadable file ${index + 1}/${files.length}: ${message}`);
             continue;
         }
+        const strategy = params.Runtime && sandboxDownloadUrl && !explicitDownloadUrl ? "browser-fetch" : "node-fetch";
+        logger?.(`[browser] Download candidate ${index + 1}/${files.length}: ${describeDownloadableCandidate(file, downloadUrl)} strategy=${strategy}`);
         try {
-            const downloaded = params.Runtime && sandboxDownloadUrl && !explicitDownloadUrl
+            const downloaded = strategy === "browser-fetch"
                 ? await fetchDownloadWithBrowser(params.Runtime, downloadUrl)
                 : await fetchDownloadWithNode(downloadUrl, getCookieHeader);
             const contentType = downloaded.contentType;
@@ -857,7 +1274,7 @@ export async function saveChatGptDownloadableFiles(params) {
                 contents: downloaded.buffer,
                 label: file.label || filename,
                 mimeType: contentType ?? file.mimeType,
-                sourceUrl: file.sandboxUrl ?? downloadUrl,
+                sourceUrl: file.sandboxUrl ?? "chatgpt-file-endpoint",
                 logger,
             });
             if (artifact) {
@@ -876,9 +1293,14 @@ export async function saveChatGptDownloadableFiles(params) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            errors.push(`${file.filename ?? file.downloadUrl ?? file.url}: ${message}`);
+            const safeMessage = safeDiagnosticText(message, 500);
+            const filename = sanitizeCandidateFilename(file.filename ??
+                filenameFromUrl(file.sandboxUrl) ??
+                filenameFromUrl(file.downloadUrl) ??
+                file.url);
+            errors.push(`${filename}: ${safeMessage}`);
             failedFiles.push(file);
-            logger?.(`[browser] Failed to save downloadable file ${index + 1}/${files.length}: ${message}`);
+            logger?.(`[browser] Failed to save downloadable file ${index + 1}/${files.length} (${describeDownloadableCandidate(file, downloadUrl)} strategy=${strategy}): ${safeMessage}`);
         }
     }
     return {
@@ -890,16 +1312,24 @@ export async function saveChatGptDownloadableFiles(params) {
     };
 }
 export async function collectChatGptFileArtifacts(params) {
-    const files = await readAssistantDownloadableFiles(params.Runtime, params.minTurnIndex ?? undefined).catch(() => []);
+    const files = await readAssistantDownloadableFiles(params.Runtime, params.minTurnIndex ?? undefined).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        params.logger?.(`[browser] Failed to inspect assistant DOM file candidates: ${safeDiagnosticText(message, 180)}`);
+        return [];
+    });
     const textFiles = readTextDownloadableFiles(params.answerText);
-    if (textFiles.length > 0) {
-        params.logger?.(`[browser] Found ${textFiles.length} downloadable file link(s) in captured answer text.`);
-    }
+    params.logger?.(`[browser] Found ${files.length} DOM downloadable file candidate(s).`);
+    params.logger?.(`[browser] Found ${textFiles.length} downloadable file link(s) in captured answer text.`);
     const allFiles = dedupeFiles([...files, ...textFiles]);
     if (allFiles.length === 0) {
         return { files: [], savedFiles: [], fileCount: 0 };
     }
     params.logger?.(`[browser] Found ${allFiles.length} downloadable file candidate(s).`);
+    allFiles.forEach((file, index) => {
+        const explicitDownloadUrl = normalizeChatGptDownloadUrl(file.downloadUrl ?? file.url);
+        const sandboxDownloadUrl = downloadUrlFromSandboxUrl(file.sandboxUrl ?? file.url);
+        params.logger?.(`[browser] Candidate ${index + 1}/${allFiles.length}: ${describeDownloadableCandidate(file, explicitDownloadUrl ?? sandboxDownloadUrl)}`);
+    });
     const saved = await saveChatGptDownloadableFiles({
         Network: params.Network,
         Runtime: params.Runtime,
@@ -924,6 +1354,7 @@ export async function collectChatGptFileArtifacts(params) {
     if (savedFiles.length === 0 && !saved.saved) {
         const detail = saved.errors.length > 0 ? `\n${saved.errors.join("\n")}` : "";
         params.logger?.(`[browser] Auto-save for downloadable files failed; returning metadata only.${detail}`);
+        params.logger?.(`[browser] WARNING: ${allFiles.length} downloadable candidate(s) existed, but no local browser-host artifact was saved; bridge artifact-ready will not be emitted until ChatGPT file capture succeeds.`);
     }
     else {
         params.logger?.(`[browser] Saved ${savedFiles.length} downloadable file artifact(s).`);