codex-chatgpt-control 0.2.0-alpha.1 → 0.5.0-alpha.1

package/dist/src/commands/conversation.d.ts

@@ -0,0 +1,15 @@
+import type { PageLike } from "../types.js";
+export type ConversationTarget = {
+    href?: string;
+    url: string;
+};
+export type EnsureConversationTargetOptions = {
+    timeoutMs: number;
+};
+export type EnsureConversationTargetResult = {
+    navigated: boolean;
+    targetUrl: string;
+    expectedConversationId?: string;
+};
+export declare function ensureConversationTarget(page: PageLike, target: ConversationTarget, options: EnsureConversationTargetOptions): Promise<EnsureConversationTargetResult>;
+export declare function waitForConversationHydrated(page: PageLike, timeoutMs: number, expectedConversationId?: string): Promise<void>;

package/dist/src/commands/conversation.js

@@ -0,0 +1,44 @@
+import { parseConversationId } from "../browser/page-state.js";
+import { countPageMessages, readLatestMessageText } from "../dom/messages.js";
+const CHATGPT_HOME = "https://chatgpt.com/";
+export async function ensureConversationTarget(page, target, options) {
+    const targetUrl = absoluteConversationUrl(target);
+    const expectedConversationId = parseConversationId(targetUrl);
+    const currentUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+    if (expectedConversationId !== undefined
+        && parseConversationId(typeof currentUrl === "string" ? currentUrl : "") === expectedConversationId) {
+        await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
+        return ensureResult(false, targetUrl, expectedConversationId);
+    }
+    await page.goto?.(targetUrl, { waitUntil: "domcontentloaded", timeout: options.timeoutMs });
+    await waitForConversationHydrated(page, options.timeoutMs, expectedConversationId);
+    return ensureResult(true, targetUrl, expectedConversationId);
+}
+export async function waitForConversationHydrated(page, timeoutMs, expectedConversationId) {
+    const started = Date.now();
+    do {
+        const url = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
+        const urlMatches = expectedConversationId === undefined || parseConversationId(typeof url === "string" ? url : "") === expectedConversationId;
+        const count = await countPageMessages(page).catch(() => 0);
+        const latestAssistantText = await readLatestMessageText(page, "assistant").catch(() => undefined);
+        const title = typeof page.title === "function" ? await page.title().catch(() => "") : "";
+        if (urlMatches && ((latestAssistantText?.trim().length ?? 0) > 0 || (count > 0 && title.length > 0 && title !== "ChatGPT"))) {
+            await page.waitForTimeout?.(250);
+            return;
+        }
+        await page.waitForTimeout?.(500);
+    } while (Date.now() - started < timeoutMs);
+}
+function absoluteConversationUrl(target) {
+    if (target.href !== undefined && target.href.startsWith("/")) {
+        return new URL(target.href, CHATGPT_HOME).toString();
+    }
+    return target.href ?? target.url;
+}
+function ensureResult(navigated, targetUrl, expectedConversationId) {
+    const result = { navigated, targetUrl };
+    if (expectedConversationId !== undefined) {
+        result.expectedConversationId = expectedConversationId;
+    }
+    return result;
+}

package/dist/src/commands/deadline.d.ts

@@ -0,0 +1,8 @@
+export type Deadline = {
+    startedAtMs: number;
+    timeoutMs: number;
+    expiresAtMs: number;
+};
+export declare function createDeadline(timeoutMs: number, startedAtMs?: number): Deadline;
+export declare function remainingMs(deadline: Deadline, nowMs?: number): number;
+export declare function childTimeoutMs(deadline: Deadline, capMs: number, nowMs?: number): number;

package/dist/src/commands/deadline.js

@@ -0,0 +1,14 @@
+export function createDeadline(timeoutMs, startedAtMs = Date.now()) {
+    const safeTimeoutMs = Math.max(0, timeoutMs);
+    return {
+        startedAtMs,
+        timeoutMs: safeTimeoutMs,
+        expiresAtMs: startedAtMs + safeTimeoutMs,
+    };
+}
+export function remainingMs(deadline, nowMs = Date.now()) {
+    return Math.max(0, deadline.expiresAtMs - nowMs);
+}
+export function childTimeoutMs(deadline, capMs, nowMs = Date.now()) {
+    return Math.max(0, Math.min(Math.max(0, capMs), remainingMs(deadline, nowMs)));
+}

package/dist/src/commands/doctor.js

@@ -3,6 +3,7 @@ import { access, stat } from "node:fs/promises";
 import { readSystemClipboard } from "../browser/clipboard.js";
 import { readPageState } from "../browser/page-state.js";
 import { localeLabels } from "../dom/locale-labels.js";
+import { localeCoverageSummary } from "../dom/locale/index.js";
 import { BROWSER_BRIDGE_REMEDIATION, resultOk } from "../errors.js";
 import { explainCommandBlocker } from "../diagnostics/blockers.js";
 import { preflightFiles } from "./files.js";
@@ -31,6 +32,7 @@ const REQUIRED_LOCALE_KEYS = [
     "rateLimitBlocker"
 ];
 const REQUIRED_TOOL_IDS = ["web_search", "deep_research", "create_image"];
+const REQUIRED_MODE_OPTION_IDS = ["latest", "instant", "thinking", "extended", "medium", "high", "extraHigh", "pro"];
 export async function doctor(env, args = {}) {
     const wanted = args.check ?? DEFAULT_CHECKS;
     const checks = {};
@@ -229,27 +231,69 @@ async function filePreflightCheck(env, args) {
 function localizationCheck(env) {
     const requiredKeysMissing = REQUIRED_LOCALE_KEYS.filter(key => localeLabels[key].length === 0);
     const missingToolIds = REQUIRED_TOOL_IDS.filter(id => (localeLabels.tools[id]?.length ?? 0) === 0);
+    const missingModeOptionIds = REQUIRED_MODE_OPTION_IDS.filter(id => (localeLabels.modeOptions[id]?.length ?? 0) === 0);
     const toolIds = Object.keys(localeLabels.tools);
+    const modeOptionIds = Object.keys(localeLabels.modeOptions);
+    const proAliases = [...localeLabels.modeOptions.pro];
+    const supportsProExtendedAlias = proAliases.some(alias => /pro\s*(?:•\s*)?extended/i.test(alias))
+        && proAliases.some(alias => /extended\s+pro/i.test(alias));
+    const runningStateLocalizationSupport = runningStateSupport();
+    const runningStateLabelCoverage = {
+        support: runningStateLocalizationSupport,
+        stopControlCandidateCount: localeLabels.stopControl.length,
+        stoppedAssistantCandidateCount: localeLabels.stoppedAssistant.length,
+        ...localeCoverageSummary.runningState,
+        registeredLocaleCount: localeCoverageSummary.registeredLocaleCount,
+        nonEnglishLocaleCount: localeCoverageSummary.nonEnglishLocaleCount
+    };
     const englishCanonicalPresent = localeLabels.composerTextbox[0] === "Chat with ChatGPT"
         && localeLabels.sendButton[0] === "Send prompt"
         && localeLabels.modeLabels.includes("Thinking")
+        && localeLabels.modeOptions.pro?.[0] === "Pro"
         && localeLabels.tools.web_search?.[0] === "Web search";
     const labelCandidateCount = REQUIRED_LOCALE_KEYS.reduce((total, key) => total + localeLabels[key].length, 0)
-        + Object.values(localeLabels.tools).reduce((total, values) => total + values.length, 0);
+        + Object.values(localeLabels.tools).reduce((total, values) => total + values.length, 0)
+        + Object.values(localeLabels.modeOptions).reduce((total, values) => total + values.length, 0);
     const details = {
         englishCanonicalPresent,
         requiredKeysMissing,
         missingToolIds,
+        missingModeOptionIds,
         toolIds,
+        modeOptionIds,
+        proAliases,
+        supportsProExtendedAlias,
+        runningStateLabelCoverage,
         labelCandidateCount,
         pageAvailable: env.page !== undefined,
         runtimeSelectorCoverage: "registry_only_stage_2"
     };
-    if (englishCanonicalPresent && requiredKeysMissing.length === 0 && missingToolIds.length === 0) {
-        return unknown("The locale registry is loaded; localized runtime selector coverage is registry-only in Stage 2 and not fully proven.", undefined, details);
+    if (englishCanonicalPresent && requiredKeysMissing.length === 0 && missingToolIds.length === 0 && missingModeOptionIds.length === 0) {
+        const runningStateMessage = runningStateLocalizationSupport === "complete"
+            ? "running-state labels are present for every registered non-English locale"
+            : runningStateLocalizationSupport === "partial"
+                ? "running-state labels are partially localized"
+                : runningStateLocalizationSupport === "english_only"
+                    ? "running-state labels are English-only"
+                    : "running-state labels are missing";
+        return unknown(`The locale registry is loaded; localized runtime selector coverage is registry-only in Stage 2 and ${runningStateMessage}.`, undefined, details);
     }
     return blocked("The locale registry is missing canonical labels required for selector fallback.", ["Update src/dom/locale-labels.ts or src/dom/locale/* with verified visible labels before relying on localized controls."], details, "selector_drift");
 }
+function runningStateSupport() {
+    const coverage = localeCoverageSummary.runningState;
+    const hasEnglishStop = coverage.stopControlLocaleCount > coverage.nonEnglishStopControlLocaleCount;
+    const hasEnglishStopped = coverage.stoppedAssistantLocaleCount > coverage.nonEnglishStoppedAssistantLocaleCount;
+    const hasEnglishFallback = hasEnglishStop && hasEnglishStopped;
+    const allNonEnglishCovered = localeCoverageSummary.nonEnglishLocaleCount > 0
+        && coverage.nonEnglishStopControlLocaleCount >= localeCoverageSummary.nonEnglishLocaleCount
+        && coverage.nonEnglishStoppedAssistantLocaleCount >= localeCoverageSummary.nonEnglishLocaleCount;
+    if (allNonEnglishCovered)
+        return "complete";
+    if (coverage.nonEnglishStopControlLocaleCount > 0 || coverage.nonEnglishStoppedAssistantLocaleCount > 0)
+        return "partial";
+    return hasEnglishFallback ? "english_only" : "missing";
+}
 async function reportsCheck(options) {
     const destDir = options?.destDir ?? "reports/runs";
     const includeContent = options?.includeContent === true;

package/dist/src/commands/experience.d.ts

@@ -0,0 +1,12 @@
+import type { CommandResult, DetectExperienceArgs, DetectExperienceData, OpenExperienceArgs, OpenExperienceData, PageLike, RuntimeEnv } from "../types.js";
+type SurfaceSnapshot = {
+    url: string;
+    composerLabels: string[];
+    mainControls: string[];
+    mainText: string;
+};
+export declare function detectExperience(env: RuntimeEnv, args?: DetectExperienceArgs): Promise<CommandResult<DetectExperienceData>>;
+export declare function openExperience(env: RuntimeEnv, args: OpenExperienceArgs): Promise<CommandResult<OpenExperienceData>>;
+export declare function detectExperienceFromSnapshot(snapshot: SurfaceSnapshot): DetectExperienceData;
+export declare function readSurfaceSnapshot(page: PageLike): Promise<SurfaceSnapshot>;
+export {};

package/dist/src/commands/experience.js

@@ -0,0 +1,288 @@
+import { resultError, resultOk } from "../errors.js";
+import { localeLabels } from "../dom/locale-labels.js";
+import { normalizeForLabelMatch, visibleLabelMatches } from "../dom/label-match.js";
+import { contextFromPage } from "./context.js";
+import { ensurePage } from "./session.js";
+export async function detectExperience(env, args = {}) {
+    void args;
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        const data = detectExperienceFromSnapshot(await readSurfaceSnapshot(page));
+        return resultOk(data, await contextFromPage(page, {
+            experience: data.experience,
+            selectorProfile: data.selectorProfile
+        }), data.experience === "unknown"
+            ? ["The current ChatGPT surface could not be classified as Chat or Work from scoped composer evidence."]
+            : []);
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+export async function openExperience(env, args) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        const before = detectExperienceFromSnapshot(await readSurfaceSnapshot(page));
+        if (before.experience === args.experience) {
+            return resultOk({
+                experience: args.experience,
+                previousExperience: before.experience,
+                changed: false,
+                selectorProfile: before.selectorProfile
+            }, await contextFromPage(page, {
+                experience: before.experience,
+                selectorProfile: before.selectorProfile
+            }));
+        }
+        const labels = localeLabels.experienceOptions[args.experience];
+        if (!await clickUniqueExperienceControl(page, labels)) {
+            return experienceSelectorDrift(page, `No unique visible ChatGPT ${args.experience === "work" ? "Work" : "Chat"} surface control was found.`, before);
+        }
+        const timeoutMs = args.timeoutMs ?? 30000;
+        const started = Date.now();
+        let after = before;
+        while (Date.now() - started < timeoutMs) {
+            await page.waitForTimeout?.(250);
+            after = detectExperienceFromSnapshot(await readSurfaceSnapshot(page));
+            if (after.experience === args.experience) {
+                return resultOk({
+                    experience: args.experience,
+                    previousExperience: before.experience,
+                    changed: true,
+                    selectorProfile: after.selectorProfile
+                }, await contextFromPage(page, {
+                    experience: after.experience,
+                    selectorProfile: after.selectorProfile
+                }));
+            }
+        }
+        return {
+            ok: false,
+            status: "blocked",
+            warnings: [],
+            blocker: {
+                kind: "selector_drift",
+                code: "experience_postcondition_unverified",
+                fieldPath: "experience",
+                message: `The ${args.experience} surface control was clicked, but the composer did not verify that ChatGPT switched to ${args.experience}.`,
+                candidates: labels.map(label => ({ label })),
+                resumable: true
+            },
+            context: await contextFromPage(page, {
+                experience: after.experience,
+                selectorProfile: after.selectorProfile
+            })
+        };
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+export function detectExperienceFromSnapshot(snapshot) {
+    const evidence = [];
+    const composerLabels = snapshot.composerLabels.map(normalizeForLabelMatch);
+    const controls = snapshot.mainControls.map(normalizeForLabelMatch);
+    const mainText = normalizeForLabelMatch(snapshot.mainText);
+    const url = snapshot.url.toLowerCase();
+    const workComposer = matchingLabels(composerLabels, localeLabels.workComposerTextbox);
+    for (const label of workComposer) {
+        evidence.push({ source: "composer", label });
+    }
+    const chatComposer = matchingLabels(composerLabels, localeLabels.composerTextbox);
+    for (const label of chatComposer) {
+        evidence.push({ source: "composer", label });
+    }
+    const workAxisCount = ["model", "effort", "speed"]
+        .filter(axis => hasAnyLabel(controls, localeLabels.configurationAxes[axis]))
+        .length;
+    if (workAxisCount >= 2) {
+        evidence.push({ source: "control", label: `Work configuration axes (${workAxisCount}/3)` });
+    }
+    if (/\/work(?:\/|$|\?)/.test(url)) {
+        evidence.push({ source: "url", label: snapshot.url });
+    }
+    if (containsAny(mainText, ["work on something else", "work on anything"])) {
+        evidence.push({ source: "heading", label: "Work composer copy" });
+    }
+    const workScore = workComposer.length * 4
+        + (workAxisCount >= 2 ? 4 : 0)
+        + (/\/work(?:\/|$|\?)/.test(url) ? 3 : 0)
+        + (containsAny(mainText, ["work on something else", "work on anything"]) ? 2 : 0);
+    const chatScore = chatComposer.length * 4;
+    let experience = "unknown";
+    let confidence = "low";
+    if (workScore > chatScore && workScore >= 4) {
+        experience = "work";
+        confidence = workScore >= 7 ? "high" : "medium";
+    }
+    else if (chatScore > workScore && chatScore >= 4) {
+        experience = "chat";
+        confidence = "high";
+    }
+    const selectorProfile = profileFromSnapshot(snapshot, experience);
+    return { experience, selectorProfile, confidence, evidence };
+}
+export async function readSurfaceSnapshot(page) {
+    const url = typeof page.url === "function"
+        ? await Promise.resolve(page.url()).catch(() => "")
+        : "";
+    if (typeof page.evaluate !== "function") {
+        return { url, composerLabels: [], mainControls: [], mainText: "" };
+    }
+    const snapshot = await page.evaluate(() => {
+        const visible = (element) => {
+            const html = element;
+            const rect = html.getBoundingClientRect?.();
+            const style = typeof window !== "undefined" ? window.getComputedStyle?.(html) : undefined;
+            return (rect === undefined || (rect.width > 0 && rect.height > 0))
+                && style?.display !== "none"
+                && style?.visibility !== "hidden"
+                && style?.opacity !== "0";
+        };
+        const labelFor = (element) => {
+            const html = element;
+            return element.getAttribute("aria-label")
+                ?? element.getAttribute("placeholder")
+                ?? html.innerText
+                ?? element.textContent
+                ?? "";
+        };
+        const normalize = (value) => value.replace(/\s+/g, " ").trim();
+        const composerRoots = Array.from(document.querySelectorAll("main form, main [data-testid*='composer' i], main [class*='composer' i]"));
+        const composerNodes = composerRoots.flatMap(root => [
+            root,
+            ...Array.from(root.querySelectorAll("textarea, [contenteditable='true'], [role='textbox'], input"))
+        ]);
+        const composerLabels = Array.from(new Set(composerNodes
+            .filter(visible)
+            .map(labelFor)
+            .map(normalize)
+            .filter(Boolean)))
+            .slice(0, 16);
+        const main = document.querySelector("main");
+        const overlayRoots = Array.from(document.querySelectorAll("[role='menu'], [role='listbox'], [data-radix-popper-content-wrapper], [data-radix-menu-content]")).filter(visible);
+        const controlRoots = Array.from(new Set([...composerRoots, ...overlayRoots]));
+        const effectiveControlRoots = controlRoots.length > 0
+            ? controlRoots
+            : main === null ? [] : [main];
+        const mainControls = Array.from(new Set(effectiveControlRoots.flatMap(root => Array.from(root.querySelectorAll("button, [role='button'], [role='menuitem'], [role='menuitemradio'], [role='option']")))
+            .filter(visible)
+            .map(labelFor)
+            .map(normalize)
+            .filter(Boolean)))
+            .slice(0, 120);
+        const surfaceTextNodes = main === null ? [] : Array.from(main.querySelectorAll("h1, h2, h3, form, [data-testid*='composer' i], [class*='composer' i]"))
+            .filter(visible)
+            .slice(0, 32);
+        const mainText = normalize(surfaceTextNodes.map(labelFor).join(" ")).slice(0, 2000);
+        return { composerLabels, mainControls, mainText };
+    }).catch(() => ({ composerLabels: [], mainControls: [], mainText: "" }));
+    return { url, ...snapshot };
+}
+function profileFromSnapshot(snapshot, experience) {
+    const controls = snapshot.mainControls.map(normalizeForLabelMatch);
+    const mainText = normalizeForLabelMatch(snapshot.mainText);
+    if (experience === "work") {
+        return hasAnyLabel(controls, localeLabels.configurationAxes.advanced)
+            || containsAny(mainText, localeLabels.configurationAxes.advanced)
+            ? "work_advanced_v1"
+            : "work_basic_v1";
+    }
+    if (experience !== "chat") {
+        return "unknown";
+    }
+    const simplifiedOptions = [
+        ...localeLabels.configurationOptions.instant,
+        ...localeLabels.configurationOptions.medium,
+        ...localeLabels.configurationOptions.high,
+        ...localeLabels.configurationOptions.extraHigh,
+        ...localeLabels.configurationOptions.pro,
+    ];
+    if (hasAnyLabel(controls, simplifiedOptions)) {
+        return "chat_simplified_v1";
+    }
+    const legacyOptions = [
+        ...localeLabels.modeOptions.latest,
+        ...localeLabels.modeOptions.thinking,
+        ...localeLabels.modeOptions.extended,
+    ];
+    return hasAnyLabel(controls, legacyOptions)
+        ? "chat_legacy_v1"
+        : "chat_simplified_v1";
+}
+async function clickUniqueExperienceControl(page, labels) {
+    for (const label of labels) {
+        for (const role of ["button", "menuitem", "tab", "link"]) {
+            if (await clickIfUnique(page.getByRole?.(role, { name: label, exact: true }))) {
+                return true;
+            }
+        }
+    }
+    if (typeof page.evaluate !== "function") {
+        return false;
+    }
+    return page.evaluate((wantedLabels) => {
+        const normalize = (value) => value.replace(/\s+/g, " ").trim().toLocaleLowerCase();
+        const wanted = new Set(wantedLabels.map(normalize));
+        const nodes = Array.from(document.querySelectorAll("header button, header [role='button'], header [role='tab'], main [role='menuitem'], main [role='option']"));
+        const matches = nodes.filter(node => {
+            const html = node;
+            const label = node.getAttribute("aria-label") ?? html.innerText ?? node.textContent ?? "";
+            return wanted.has(normalize(label));
+        });
+        if (matches.length !== 1)
+            return false;
+        matches[0].click();
+        return true;
+    }, labels).catch(() => false);
+}
+async function clickIfUnique(locator) {
+    if (locator?.count === undefined || locator.click === undefined) {
+        return false;
+    }
+    if (await locator.count().catch(() => 0) !== 1) {
+        return false;
+    }
+    await locator.click();
+    return true;
+}
+function matchingLabels(normalizedHaystack, candidates) {
+    const normalizedCandidates = candidates.map(normalizeForLabelMatch);
+    return normalizedHaystack
+        .filter(label => normalizedCandidates.some(candidate => label === candidate || visibleLabelMatches(label, candidate)))
+        .slice(0, 4);
+}
+function hasAnyLabel(normalizedHaystack, candidates) {
+    const normalizedCandidates = candidates.map(normalizeForLabelMatch);
+    return normalizedHaystack.some(label => normalizedCandidates.some(candidate => label === candidate || visibleLabelMatches(label, candidate)));
+}
+function containsAny(normalizedText, candidates) {
+    return candidates.map(normalizeForLabelMatch).some(candidate => normalizedText.includes(candidate));
+}
+async function experienceSelectorDrift(page, message, detected) {
+    return {
+        ok: false,
+        status: "unsupported",
+        warnings: [],
+        blocker: {
+            kind: "selector_drift",
+            code: "experience_control_not_found",
+            fieldPath: "experience",
+            message,
+            candidates: detected.evidence.map(item => ({ label: `${item.source}: ${item.label}` })),
+            resumable: true
+        },
+        context: await contextFromPage(page, {
+            experience: detected.experience,
+            selectorProfile: detected.selectorProfile
+        })
+    };
+}

package/dist/src/commands/files.js

@@ -1,5 +1,6 @@
 import { access, readFile, stat } from "node:fs/promises";
 import { constants } from "node:fs";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import { downloadLatestArtifact, locatorCountWithTimeout } from "./artifacts.js";
 import { waitForDownloadFromClick } from "../browser/downloads.js";
@@ -8,7 +9,7 @@ import { addFilesButton, cssSelectors, requiredLocator } from "../dom/selectors.
 import { localeLabels } from "../dom/locale-labels.js";
 import { basenameForHostPath, isHostAbsolutePath, resolveForHostPath } from "../platform/local-paths.js";
 import { contextFromPage } from "./context.js";
-import { bootstrap } from "./session.js";
+import { ensurePage } from "./session.js";
 import { localGuardTimeout } from "./timeouts.js";
 const CODEX_UPLOAD_PERMISSION_FIX = "Codex Settings > Computer Use > Chrome > Permissions > Uploads: set to Always allow, or add chatgpt.com to the allowed upload domains.";
 const CHROME_FILE_URL_PERMISSION_FIX = "Chrome chrome://extensions > Codex extension > Details: enable Allow access to file URLs.";
@@ -103,7 +104,17 @@ export async function preflightFiles(env, args) {
                 message: `File attachment exceeds the configured per-file preflight limit: ${absolute} (${fileStat.size}/${maxBytesPerFile} bytes)`
             });
         }
-        const metadata = fileMetadata(absolute, fileStat.size);
+        if (fileStat.size === 0) {
+            return filePreflightBlocker({
+                env,
+                status: "blocked",
+                kind: "upload_failed",
+                code: "file_empty",
+                fieldPath,
+                message: `File attachment path is zero bytes and ChatGPT rejects empty attachments: ${absolute}`
+            });
+        }
+        const metadata = await fileMetadata(absolute, fileStat.size, args.includeHashes === true);
         files.push(metadata);
     }
     const totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
@@ -121,7 +132,11 @@ export async function preflightFiles(env, args) {
     return resultOk({ files, totalBytes }, filePreflightContext(env), warnings);
 }
 export async function attachFiles(env, args) {
-    const preflight = await preflightFiles(env, { paths: args.paths });
+    const preflightArgs = { paths: args.paths };
+    if (args.includeDiagnostics === true && args.includeHashes !== undefined) {
+        preflightArgs.includeHashes = args.includeHashes;
+    }
+    const preflight = await preflightFiles(env, preflightArgs);
     if (!preflight.ok || preflight.data === undefined) {
         return preflight;
     }
@@ -137,6 +152,9 @@ export async function attachFiles(env, args) {
             bytes: file.bytes
         }));
         await uploadFiles(page, files, args.timeoutMs ?? 30000);
+        const browserInput = args.includeDiagnostics === true
+            ? await readBrowserInputDiagnostic(page).catch(() => undefined)
+            : undefined;
         await page.waitForTimeout?.(args.timeoutMs === undefined ? 1000 : Math.min(args.timeoutMs, 3000));
         const readiness = await waitForAttachedFilesReady(page, files, args.timeoutMs ?? 30000);
         if (!readiness.ready) {
@@ -169,7 +187,14 @@ export async function attachFiles(env, args) {
                 context: await contextFromPage(page)
             };
         }
-        return resultOk({ files }, await contextFromPage(page), preflight.warnings);
+        const data = { files };
+        if (args.includeDiagnostics === true) {
+            data.diagnostics = { preflight: preflight.data };
+            if (browserInput !== undefined) {
+                data.diagnostics.browserInput = browserInput;
+            }
+        }
+        return resultOk(data, await contextFromPage(page), preflight.warnings);
     }
     catch (error) {
         if (isUploadBridgeBlocker(error)) {
@@ -209,10 +234,10 @@ function filePreflightBlocker(args) {
 function filePreflightContext(env) {
     return { timestamp: (env.now?.() ?? new Date()).toISOString() };
 }
-function fileMetadata(absolute, bytes) {
+async function fileMetadata(absolute, bytes, includeHash = false) {
     const extension = extensionForHostPath(absolute);
     const { mimeType, category } = guessFileType(extension);
-    return {
+    const metadata = {
         path: absolute,
         name: basenameForHostPath(absolute),
         bytes,
@@ -220,6 +245,10 @@ function fileMetadata(absolute, bytes) {
         mimeType,
         category
     };
+    if (includeHash) {
+        metadata.sha256 = createHash("sha256").update(await readFile(absolute)).digest("hex");
+    }
+    return metadata;
 }
 function extensionForHostPath(value) {
     return process.platform === "win32"
@@ -230,9 +259,6 @@ function collectFilePreflightWarnings(files, warnings) {
     const byPath = new Map();
     const byName = new Map();
     for (const file of files) {
-        if (file.bytes === 0) {
-            warnings.push(`Zero-byte file will be attached if ChatGPT accepts it: ${file.name}`);
-        }
         const pathCount = (byPath.get(file.path) ?? 0) + 1;
         byPath.set(file.path, pathCount);
         if (pathCount === 2) {
@@ -556,11 +582,33 @@ async function setHiddenFileInput(page, files) {
     }
     await input.setInputFiles(files.map(file => file.path));
 }
-async function ensurePage(env) {
-    if (env.page !== undefined) {
-        return resultOk({}, await contextFromPage(env.page));
+async function readBrowserInputDiagnostic(page) {
+    if (typeof page.evaluate !== "function") {
+        return undefined;
     }
-    return bootstrap(env, { preferExistingTab: true });
+    return page.evaluate(() => {
+        const input = (document.querySelector("#upload-files")
+            || document.querySelector("input[type='file']:not([accept='image/*'])")
+            || document.querySelector("input[type='file']"));
+        if (!input) {
+            return { files: [] };
+        }
+        return {
+            files: Array.from(input.files ?? []).map(file => {
+                const diagnostic = {
+                    name: file.name,
+                    size: file.size
+                };
+                if (file.type.length > 0) {
+                    diagnostic.type = file.type;
+                }
+                if (file.lastModified !== 0) {
+                    diagnostic.lastModified = file.lastModified;
+                }
+                return diagnostic;
+            })
+        };
+    });
 }
 async function setFilesViaDomDataTransfer(page, files) {
     const totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);

package/dist/src/commands/messages.d.ts

@@ -1,5 +1,5 @@
 import { type AssistantGenerationState } from "../dom/generation-state.js";
-import type { AskArgs, AskReadData, CommandResult, ComposeArgs, ComposeData, ReadLatestArgs, ReadLatestData, RuntimeEnv, SubmitArgs, SubmitData, WaitAndReadArgs, WaitArgs, WaitData } from "../types.js";
+import type { AskArgs, AskReadData, CommandResult, ComposeArgs, ComposeData, MessageStatusArgs, MessageStatusData, ReadLatestArgs, ReadLatestData, RuntimeEnv, SubmitArgs, SubmitData, WaitAndReadArgs, WaitArgs, WaitData } from "../types.js";
 export type CompletionSnapshot = {
     textStableForMs: number;
     stableMs: number;
@@ -12,6 +12,7 @@ export declare function composeMessage(env: RuntimeEnv, args: ComposeArgs): Prom
 export declare function submitMessage(env: RuntimeEnv, args?: SubmitArgs): Promise<CommandResult<SubmitData>>;
 export declare function waitForMessage(env: RuntimeEnv, args?: WaitArgs): Promise<CommandResult<WaitData>>;
 export declare function readLatest(env: RuntimeEnv, args?: ReadLatestArgs): Promise<CommandResult<ReadLatestData>>;
+export declare function messageStatus(env: RuntimeEnv, args?: MessageStatusArgs): Promise<CommandResult<MessageStatusData>>;
 export declare function askMessage(env: RuntimeEnv, args: AskArgs): Promise<CommandResult<AskReadData>>;
 export declare function waitAndRead(env: RuntimeEnv, args?: WaitAndReadArgs): Promise<CommandResult<AskReadData>>;
 export declare function submittedUserTurnMatches(actual: string | undefined, wanted: string | undefined): boolean;