codex-chatgpt-control 0.3.0-alpha.1 → 0.5.1-alpha.1

package/dist/src/commands/files.js

@@ -7,10 +7,10 @@ import { waitForDownloadFromClick } from "../browser/downloads.js";
 import { resultError, resultOk } from "../errors.js";
 import { addFilesButton, cssSelectors, requiredLocator } from "../dom/selectors.js";
 import { localeLabels } from "../dom/locale-labels.js";
-import { basenameForHostPath, isHostAbsolutePath, resolveForHostPath } from "../platform/local-paths.js";
+import { basenameForHostPath, currentHostPathPlatform, isHostAbsolutePath, resolveForHostPath } from "../platform/local-paths.js";
 import { contextFromPage } from "./context.js";
-import { bootstrap } from "./session.js";
-import { localGuardTimeout } from "./timeouts.js";
+import { ensurePage } from "./session.js";
+import { localGuardTimeout, withTimeout } 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.";
 const DEFAULT_MAX_BYTES_PER_FILE = 512 * 1024 * 1024;
@@ -251,7 +251,7 @@ async function fileMetadata(absolute, bytes, includeHash = false) {
     return metadata;
 }
 function extensionForHostPath(value) {
-    return process.platform === "win32"
+    return currentHostPathPlatform() === "win32"
         ? path.win32.extname(value).toLowerCase()
         : path.posix.extname(value).toLowerCase();
 }
@@ -526,6 +526,24 @@ export async function downloadLatestFile(env, args) {
     }
     const page = env.page;
     try {
+        const generatedFileDownload = await tryGeneratedFilePreviewDownload(page, args);
+        if (generatedFileDownload !== undefined) {
+            return generatedFileDownload;
+        }
+        if (args.filenamePattern !== undefined) {
+            return {
+                ok: false,
+                status: "unsupported",
+                warnings: [],
+                blocker: {
+                    kind: "download_unavailable",
+                    code: "download_filename_not_found",
+                    message: `No visible ChatGPT file affordance matched filenamePattern ${JSON.stringify(args.filenamePattern)}.`,
+                    resumable: true
+                },
+                context: await contextFromPage(page)
+            };
+        }
         const controls = requiredLocator(page, cssSelectors.downloadControls);
         let count;
         try {
@@ -571,6 +589,144 @@ export async function downloadLatestFile(env, args) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
     }
 }
+async function tryGeneratedFilePreviewDownload(page, args) {
+    const timeoutMs = args.timeoutMs ?? 120000;
+    const candidates = await inspectGeneratedFileAffordances(page, localGuardTimeout(timeoutMs, 5000));
+    const selected = selectGeneratedFileAffordance(candidates, args);
+    if (selected === undefined)
+        return undefined;
+    try {
+        const assistantMessages = requiredLocator(page, cssSelectors.assistantMessages);
+        const assistantCount = await locatorCountWithTimeout(assistantMessages, localGuardTimeout(timeoutMs, 5000), "generated_file_assistant_count_timeout");
+        if (selected.assistantIndex < 0 || selected.assistantIndex >= assistantCount) {
+            throw new Error("The selected generated-file assistant turn is no longer present.");
+        }
+        const assistant = assistantMessages.nth?.(selected.assistantIndex) ?? assistantMessages;
+        const role = selected.tag === "button" ? "button" : "link";
+        const affordance = assistant.getByRole?.(role, { name: selected.filename, exact: true })
+            ?? assistant.locator?.(`${selected.tag}[aria-label="${escapeCssAttribute(selected.filename)}"]`);
+        const affordanceCount = await locatorCountWithTimeout(affordance, localGuardTimeout(timeoutMs, 5000), "generated_file_affordance_count_timeout");
+        if (affordance === undefined || affordanceCount !== 1 || typeof affordance.click !== "function") {
+            throw new Error(`Expected one clickable generated-file affordance for ${selected.filename}, found ${affordanceCount}.`);
+        }
+        if (selected.tag === "a") {
+            const downloaded = await waitForDownloadFromClick(page, () => affordance.click({ timeoutMs: localGuardTimeout(timeoutMs, 10000) }), args.destDir, timeoutMs, selected.filename);
+            return resultOk(downloaded, await contextFromPage(page));
+        }
+        await affordance.click({ timeoutMs: localGuardTimeout(timeoutMs, 10000) });
+        const preview = requiredLocator(page, `section[aria-label="${escapeCssAttribute(selected.filename)}"]`);
+        const download = await waitForPreviewDownloadControl(page, preview, timeoutMs);
+        if (download === undefined) {
+            throw new Error(`The artifact preview for ${selected.filename} did not expose a visible Download control.`);
+        }
+        const downloaded = await waitForDownloadFromClick(page, async () => download.click?.({ timeoutMs: localGuardTimeout(timeoutMs, 10000) }), args.destDir, timeoutMs, selected.filename);
+        return resultOk(downloaded, await contextFromPage(page));
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+async function inspectGeneratedFileAffordances(page, timeoutMs) {
+    if (typeof page.evaluate === "function") {
+        const fromDom = await withTimeout(page.evaluate(() => {
+            const visible = (element) => {
+                let current = element;
+                while (current !== null) {
+                    const html = current;
+                    const style = window.getComputedStyle(html);
+                    const rect = html.getBoundingClientRect();
+                    if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity || "1") <= 0)
+                        return false;
+                    if (current === element && (rect.width <= 0 || rect.height <= 0))
+                        return false;
+                    current = current.parentElement;
+                }
+                return true;
+            };
+            const fileLike = (value) => /^[^\\/\r\n]{1,255}\.[a-z0-9][a-z0-9._-]{0,15}$/i.test(value);
+            const assistants = Array.from(document.querySelectorAll("[data-message-author-role='assistant']"));
+            return assistants.flatMap((assistant, assistantIndex) => Array.from(assistant.querySelectorAll("button[aria-label], a[download], a[href*='/backend-api/files/']"))
+                .filter(visible)
+                .map(element => ({
+                assistantIndex,
+                filename: (element.getAttribute("aria-label") ?? element.textContent ?? "").trim(),
+                tag: element.tagName.toLocaleLowerCase(),
+                text: (element.textContent ?? "").trim()
+            }))
+                .filter(item => (item.tag === "button" || item.tag === "a") && fileLike(item.filename) && item.filename === item.text)
+                .map(({ assistantIndex, filename, tag }) => ({ assistantIndex, filename, tag })));
+        }), timeoutMs, "Timed out while inspecting generated-file buttons.").catch(() => undefined);
+        if (Array.isArray(fromDom))
+            return fromDom;
+    }
+    if (typeof page.content !== "function")
+        return [];
+    const html = await withTimeout(page.content(), timeoutMs, "Timed out while reading generated-file button markup.").catch(() => "");
+    const candidates = [];
+    const buttonPattern = /<(button|a)\b[^>]*\baria-label=(['"])(.*?)\2[^>]*>([\s\S]*?)<\/\1>/gi;
+    let match;
+    while ((match = buttonPattern.exec(html)) !== null) {
+        const filename = decodeBasicHtml(match[3] ?? "").trim();
+        const text = decodeBasicHtml((match[4] ?? "").replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+        if (/^[^\\/\r\n]{1,255}\.[a-z0-9][a-z0-9._-]{0,15}$/i.test(filename) && filename === text) {
+            candidates.push({ assistantIndex: 0, filename, tag: (match[1] ?? "button").toLocaleLowerCase() });
+        }
+    }
+    return candidates;
+}
+function selectGeneratedFileAffordance(candidates, args) {
+    let scoped = candidates;
+    const from = args.from;
+    if (typeof from === "object" && from !== null) {
+        scoped = scoped.filter(candidate => candidate.assistantIndex === from.assistantIndex);
+    }
+    else if (from !== "visible_conversation") {
+        const latestAssistant = Math.max(-1, ...scoped.map(candidate => candidate.assistantIndex));
+        scoped = scoped.filter(candidate => candidate.assistantIndex === latestAssistant);
+    }
+    if (args.filenamePattern !== undefined) {
+        scoped = scoped.filter(candidate => filenameMatches(candidate.filename, args.filenamePattern));
+    }
+    return scoped.at(-1);
+}
+function filenameMatches(filename, pattern) {
+    try {
+        return new RegExp(pattern, "i").test(filename);
+    }
+    catch {
+        return filename.toLocaleLowerCase().includes(pattern.toLocaleLowerCase());
+    }
+}
+async function waitForPreviewDownloadControl(page, preview, timeoutMs) {
+    const deadline = Date.now() + Math.min(timeoutMs, 15000);
+    while (Date.now() < deadline) {
+        for (const label of localeLabels.download) {
+            const control = preview.getByRole?.("button", { name: label, exact: true })
+                ?? preview.locator?.(`button[aria-label="${escapeCssAttribute(label)}"]`);
+            if (await locatorCountWithTimeout(control, localGuardTimeout(timeoutMs, 2000), "artifact_preview_download_count_timeout") === 1) {
+                return control;
+            }
+        }
+        if (typeof page.waitForTimeout === "function") {
+            await page.waitForTimeout(100);
+        }
+        else {
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+    }
+    return undefined;
+}
+function escapeCssAttribute(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/[\r\n]/g, " ");
+}
+function decodeBasicHtml(value) {
+    return value
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&amp;/gi, "&");
+}
 async function setHiddenFileInput(page, files) {
     if (page === undefined) {
         throw new Error("No active page is available for file upload.");
@@ -610,12 +766,6 @@ async function readBrowserInputDiagnostic(page) {
         };
     });
 }
-async function ensurePage(env) {
-    if (env.page !== undefined) {
-        return resultOk({}, await contextFromPage(env.page));
-    }
-    return bootstrap(env, { preferExistingTab: true });
-}
 async function setFilesViaDomDataTransfer(page, files) {
     const totalBytes = files.reduce((sum, file) => sum + file.bytes, 0);
     const maxInlineBytes = 25 * 1024 * 1024;

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;

package/dist/src/commands/messages.js

@@ -10,7 +10,7 @@ import { contextFromPage } from "./context.js";
 import { createDeadline } from "./deadline.js";
 import { withCommandOutputText } from "./output.js";
 import { createSingleFlightProbe } from "./probes.js";
-import { bootstrap } from "./session.js";
+import { ensurePage } from "./session.js";
 export function isResponseComplete(snapshot) {
     return snapshot.latestText.trim().length > 0
         && !isTransientAssistantText(snapshot.latestText)
@@ -98,8 +98,14 @@ export async function submitMessage(env, args = {}) {
         }
         if (userTurn === undefined) {
             const latestUser = await readLatestMessage(page, "user", "normalized_text");
+            const generation = await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE);
+            const turnCount = await countPageMessages(page).catch(() => undefined);
             if (submittedUserTurnMatches(latestUser?.text, args.text)) {
-                return resultOk(submitData(latestUser?.text, await countPageMessages(page).catch(() => undefined)), await contextFromPage(page));
+                return resultOk(submitData(latestUser?.text, turnCount, generation.active ? "submitted_generating" : "submitted", generation), await contextFromPage(page));
+            }
+            const turnAdvanced = previousTurnCount !== undefined && turnCount !== undefined && turnCount > previousTurnCount;
+            if (turnAdvanced || generation.active) {
+                return resultOk(submitData(undefined, turnCount, generation.active ? "submitted_generating" : "submitted_unconfirmed", generation), await contextFromPage(page), ["Submitted prompt could not be matched to a rendered user turn yet, but ChatGPT page state indicates progress."]);
             }
             return {
                 ok: false,
@@ -113,7 +119,7 @@ export async function submitMessage(env, args = {}) {
                 context: await contextFromPage(page)
             };
         }
-        return resultOk(submitData(userTurn, await countPageMessages(page).catch(() => undefined)), await contextFromPage(page));
+        return resultOk(submitData(userTurn, await countPageMessages(page).catch(() => undefined), "submitted", await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE)), await contextFromPage(page));
     }
     catch (error) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
@@ -287,6 +293,7 @@ export async function waitForMessage(env, args = {}) {
     let lastChangedAt = Date.now();
     let lastObservedTextLength = 0;
     let latestAssistantCount = await countPageMessages(page, "assistant").catch(() => 0);
+    let lastGeneration = EMPTY_GENERATION_STATE;
     while (Date.now() - started < timeoutMs) {
         const probeResult = await waitSnapshotProbe(page, deadline, { timeoutMs: probeTimeoutMs });
         addWarnings(waitWarnings, probeResult.warnings);
@@ -317,6 +324,7 @@ export async function waitForMessage(env, args = {}) {
         }
         pollIndex += 1;
         const hasResponseActions = await resolveResponseActions(page, snapshot);
+        lastGeneration = snapshot.generation;
         if (targetReached && snapshot.generation.stopped && snapshot.text.length > 0) {
             const stoppedText = normalizeWhitespace(await fetchLatestAssistantText(page) ?? "");
             // A failed re-read must not fabricate an empty capture: real text was observed in
@@ -324,6 +332,9 @@ export async function waitForMessage(env, args = {}) {
             const data = stoppedText.length > 0
                 ? waitDataFromText(args, false, stoppedText, latestAssistantCount, Date.now() - started)
                 : waitDataWithoutText(latestAssistantCount, Date.now() - started);
+            data.completionState = "stopped";
+            data.generationActive = snapshot.generation.active;
+            data.generationSignals = snapshot.generation.signals;
             if (stoppedText.length === 0) {
                 waitWarnings.add(`The interrupted assistant text (~${snapshot.text.length} chars observed) could not be re-read at wait exit; call messages.readLatest on the same thread to capture it.`);
             }
@@ -361,6 +372,9 @@ export async function waitForMessage(env, args = {}) {
             };
             if (fetchedMetadata.hash === snapshot.text.hash && isResponseComplete(completionSnapshot)) {
                 const data = waitDataFromText(args, true, latestText, latestAssistantCount, Date.now() - started);
+                data.completionState = "complete";
+                data.generationActive = false;
+                data.generationSignals = snapshot.generation.signals;
                 return withCommandOutputText(resultOk(data, await contextFromPage(page), [...waitWarnings, ...responseContentWarnings(args, true)]));
             }
             if (latestText.length > 0) {
@@ -374,7 +388,11 @@ export async function waitForMessage(env, args = {}) {
     if (lastObservedTextLength > 0) {
         const partialText = await fetchLatestAssistantText(page);
         if (partialText !== undefined && normalizeWhitespace(partialText).length > 0) {
-            const data = waitDataFromText(args, false, normalizeWhitespace(partialText), latestAssistantCount, Date.now() - started);
+            const normalizedPartialText = normalizeWhitespace(partialText);
+            const data = waitDataFromText(args, false, normalizedPartialText, latestAssistantCount, Date.now() - started);
+            data.completionState = completionStateFromGeneration(lastGeneration, false, normalizedPartialText.length > 0);
+            data.generationActive = lastGeneration.active;
+            data.generationSignals = lastGeneration.signals;
             return withCommandOutputText({
                 ok: false,
                 status: "partial",
@@ -552,9 +570,51 @@ export async function readLatest(env, args = {}) {
         data.thoughtDurationText = latest.thoughtDurationText;
     if (latest.sourcesAvailable !== undefined)
         data.sourcesAvailable = latest.sourcesAvailable;
+    if (role === "assistant") {
+        const generation = await readAssistantGenerationState(page).catch(() => EMPTY_GENERATION_STATE);
+        data.completionState = completionStateFromGeneration(generation, undefined, latest.text.trim().length > 0);
+        data.generationActive = generation.active;
+        data.generationSignals = generation.signals;
+    }
     return withCommandOutputText(resultOk(data, await contextFromPage(page), data.warnings ?? []));
 }
+export async function messageStatus(env, args = {}) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    // Reuse the combined wait-snapshot evaluate for counts and generation state in a single
+    // round trip; it never carries full assistant text, so a bounded preview is fetched
+    // separately below only when the snapshot proves an assistant turn has text.
+    const snapshot = await readWaitDomSnapshot(page).catch(() => undefined) ?? await fallbackWaitSnapshot(page, 0);
+    const maxPreviewChars = Math.max(0, args.maxPreviewChars ?? 240);
+    const latestText = snapshot.text.length > 0
+        ? normalizeWhitespace(await fetchLatestAssistantText(page) ?? "")
+        : "";
+    const data = {
+        turnCount: snapshot.turnCount,
+        assistantTurnCount: snapshot.assistantTurnCount,
+        completionState: completionStateFromGeneration(snapshot.generation, undefined, latestText.length > 0),
+        generationActive: snapshot.generation.active,
+        generationSignals: snapshot.generation.signals
+    };
+    if (snapshot.latestAssistantTurnIndex !== undefined)
+        data.latestAssistantTurnIndex = snapshot.latestAssistantTurnIndex;
+    if (latestText.length > 0) {
+        data.latestAssistantTextLength = latestText.length;
+        data.latestAssistantPreview = latestText.length > maxPreviewChars
+            ? `${latestText.slice(0, Math.max(0, maxPreviewChars - 1))}...`
+            : latestText;
+    }
+    return resultOk(data, await contextFromPage(page));
+}
 export async function askMessage(env, args) {
+    const normalizedPrompt = normalizeAskPrompt(args);
+    if (!normalizedPrompt.ok) {
+        return normalizedPrompt.result;
+    }
+    const prompt = normalizedPrompt.text;
     const boot = await ensurePage(env);
     if (!boot.ok) {
         return boot;
@@ -562,7 +622,7 @@ export async function askMessage(env, args) {
     const page = env.page;
     const beforeTurnCount = await countPageMessages(page).catch(() => undefined);
     const beforeAssistantTurnCount = await countPageMessages(page, "assistant").catch(() => undefined);
-    const composeArgs = { text: args.text, mode: "replace" };
+    const composeArgs = { text: prompt, mode: "replace" };
     if (args.timeoutMs !== undefined) {
         composeArgs.timeoutMs = args.timeoutMs;
     }
@@ -570,7 +630,7 @@ export async function askMessage(env, args) {
     if (!compose.ok) {
         return forwardFailure(compose);
     }
-    const submitArgs = { text: args.text };
+    const submitArgs = { text: prompt };
     if (beforeTurnCount !== undefined) {
         submitArgs.previousTurnCount = beforeTurnCount;
     }
@@ -627,7 +687,7 @@ export async function askMessage(env, args) {
         return forwardFailure(waitFailure);
     }
     const state = await readPageState(page).catch(() => undefined);
-    const data = { prompt: args.text };
+    const data = { prompt };
     const complete = waitResult?.data?.complete ?? (waitResult === undefined ? undefined : false);
     if (complete !== undefined) {
         data.complete = complete;
@@ -641,6 +701,7 @@ export async function askMessage(env, args) {
     if (state?.title !== undefined) {
         data.title = state.title;
     }
+    applyMessageState(data, submit.data, waitResult?.data);
     if (waitFailure !== undefined) {
         data.complete = false;
         return withCommandOutputText({
@@ -678,7 +739,7 @@ export async function waitAndRead(env, args = {}) {
         }
         return forwardFailure(read);
     }
-    const data = askReadData("", read.data?.text, wait.data?.complete);
+    const data = askReadData("", read.data?.text, wait.data?.complete, wait.data, read.data);
     const warnings = [...read.warnings, ...wait.warnings];
     if (!wait.ok && wait.status === "partial") {
         data.complete = false;
@@ -695,12 +756,6 @@ export async function waitAndRead(env, args = {}) {
     }
     return withCommandOutputText(resultOk(data, read.context, warnings));
 }
-async function ensurePage(env) {
-    if (env.page !== undefined) {
-        return resultOk({}, await contextFromPage(env.page));
-    }
-    return bootstrap(env, { preferExistingTab: true });
-}
 async function waitForSubmittedUserTurn(page, text, previousTurnCount, timeoutMs) {
     const started = Date.now();
     const wanted = text === undefined ? undefined : normalizeWhitespace(text);
@@ -820,7 +875,7 @@ async function sleep(page, ms) {
     }
     await new Promise(resolve => setTimeout(resolve, ms));
 }
-function submitData(userTurnText, turnCount) {
+function submitData(userTurnText, turnCount, submissionState, generation) {
     const data = { submitted: true };
     if (userTurnText !== undefined) {
         data.userTurnText = userTurnText;
@@ -828,9 +883,13 @@ function submitData(userTurnText, turnCount) {
     if (turnCount !== undefined) {
         data.turnCount = turnCount;
     }
+    data.submissionState = submissionState;
+    data.completionState = completionStateFromGeneration(generation);
+    data.generationActive = generation.active;
+    data.generationSignals = generation.signals;
     return data;
 }
-function askReadData(prompt, responseText, complete) {
+function askReadData(prompt, responseText, complete, wait, read) {
     const data = { prompt };
     if (responseText !== undefined) {
         data.responseText = responseText;
@@ -838,8 +897,71 @@ function askReadData(prompt, responseText, complete) {
     if (complete !== undefined) {
         data.complete = complete;
     }
+    applyMessageState(data, undefined, wait, read);
     return data;
 }
+function applyMessageState(data, submit, wait, read) {
+    if (submit?.submissionState !== undefined)
+        data.submissionState = submit.submissionState;
+    const completionState = wait?.completionState ?? read?.completionState ?? submit?.completionState;
+    if (completionState !== undefined)
+        data.completionState = completionState;
+    const generationActive = wait?.generationActive ?? read?.generationActive ?? submit?.generationActive;
+    if (generationActive !== undefined)
+        data.generationActive = generationActive;
+    const generationSignals = wait?.generationSignals ?? read?.generationSignals ?? submit?.generationSignals;
+    if (generationSignals !== undefined)
+        data.generationSignals = generationSignals;
+}
+function completionStateFromGeneration(generation, complete, hasPartialText = false) {
+    if (complete === true)
+        return "complete";
+    if (generation.active)
+        return "generating";
+    if (generation.stopped)
+        return "stopped";
+    if (complete === false || hasPartialText)
+        return "partial";
+    return "unknown";
+}
+function normalizeAskPrompt(args) {
+    const text = args.text;
+    const prompt = args.prompt;
+    if (text !== undefined && prompt !== undefined && text !== prompt) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                status: "error",
+                warnings: [],
+                error: {
+                    name: "InvalidAskArgs",
+                    message: "messages.ask received both text and prompt with different values.",
+                    recoverable: false
+                },
+                context: { timestamp: new Date().toISOString() }
+            }
+        };
+    }
+    const normalized = text ?? prompt;
+    if (normalized === undefined || normalized.trim().length === 0) {
+        return {
+            ok: false,
+            result: {
+                ok: false,
+                status: "error",
+                warnings: [],
+                error: {
+                    name: "InvalidAskArgs",
+                    message: "messages.ask requires a non-empty text or prompt argument.",
+                    recoverable: false
+                },
+                context: { timestamp: new Date().toISOString() }
+            }
+        };
+    }
+    return { ok: true, text: normalized };
+}
 function readRole(read) {
     return typeof read === "object" ? read.role : undefined;
 }

package/dist/src/commands/modes.js

@@ -4,11 +4,12 @@ import { localeLabels } from "../dom/locale-labels.js";
 import { isShortLatinToken, normalizeForLabelMatch, visibleLabelMatches } from "../dom/label-match.js";
 import { normalizeLabel, normalizeWhitespace } from "../dom/visible-text.js";
 import { contextFromPage } from "./context.js";
-import { bootstrap } from "./session.js";
+import { ensurePage } from "./session.js";
 const DEFAULT_MODE_EFFORT = "Thinking";
 const CURRENT_MODE_LABELS = dedupeLabels([
     ...localeLabels.modeLabels,
     ...Object.values(localeLabels.modeOptions).flat(),
+    ...Object.values(localeLabels.configurationOptions).flat(),
 ]);
 const MODE_OPENER_LABELS = [...CURRENT_MODE_LABELS.filter(label => label !== "Pro"), ...localeLabels.modeOpenerExtra];
 const MODEL_VERSION_FAMILY_PATTERN = /^gpt[\s-]/i;
@@ -224,12 +225,6 @@ export async function selectTool(env, args) {
         return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
     }
 }
-async function ensurePage(env) {
-    if (env.page !== undefined) {
-        return resultOk({}, await contextFromPage(env.page));
-    }
-    return bootstrap(env, { preferExistingTab: true });
-}
 async function clickFirstUniqueButton(page, labels) {
     for (const label of labels) {
         const roleLocator = page.getByRole?.("button", { name: label, exact: true });
@@ -508,22 +503,35 @@ async function selectModelVersion(page, requestedVersion, currentCandidates, tim
             candidates = await enumerateVisibleMenuItems(page);
         }
     }
-    let exact = findExactMenuItem(candidates, requestedVersion);
+    let exact = findExactSelectableMenuItem(candidates, requestedVersion);
     if (exact !== undefined) {
-        return await clickMenuItem(page, exact.label)
+        return await clickResolvedMenuItem(page, exact)
             ? { selected: exact.label, candidates: candidates.map(candidate => candidate.label) }
             : { candidates: candidates.map(candidate => candidate.label) };
     }
     const opened = await openModelVersionSubmenu(page, currentCandidates);
     candidates = await enumerateVisibleMenuItems(page);
-    exact = findExactMenuItem(candidates, requestedVersion);
+    exact = findExactSelectableMenuItem(candidates, requestedVersion);
     if (!opened || exact === undefined) {
         return { candidates: candidates.map(candidate => candidate.label) };
     }
-    return await clickMenuItem(page, exact.label)
+    return await clickResolvedMenuItem(page, exact)
         ? { selected: exact.label, candidates: candidates.map(candidate => candidate.label) }
         : { candidates: candidates.map(candidate => candidate.label) };
 }
+function isModelVersionSubmenuOpener(item) {
+    return item.hasPopup === true
+        || (item.role !== "menuitemradio" && MODEL_VERSION_FAMILY_PATTERN.test(item.label));
+}
+async function clickResolvedMenuItem(page, item) {
+    if (item.testId !== undefined && await clickIfUnique(page.locator?.(`[data-testid="${escapeAttributeValue(item.testId)}"]`))) {
+        return true;
+    }
+    if (item.role !== undefined && await clickIfUnique(page.getByRole?.(item.role, { name: item.label, exact: true }))) {
+        return true;
+    }
+    return clickMenuItem(page, item.label);
+}
 async function openModelVersionSubmenu(page, candidates) {
     const submenuOpeners = candidates.filter(item => item.hasPopup === true || MODEL_VERSION_FAMILY_PATTERN.test(item.label));
     if (submenuOpeners.length === 0) {
@@ -604,9 +612,10 @@ async function modelVersionMenuItemsAreVisible(page) {
     return (await enumerateVisibleMenuItems(page))
         .some(candidate => candidate.role === "menuitemradio" && MODEL_VERSION_LABEL_PATTERN.test(candidate.label));
 }
-function findExactMenuItem(items, wanted) {
+function findExactSelectableMenuItem(items, wanted) {
     const normalized = normalizeLabel(wanted);
-    const matches = items.filter(item => item.normalized === normalized);
+    const matches = items.filter(item => item.normalized === normalized
+        && !isModelVersionSubmenuOpener(item));
     return matches.length === 1 ? matches[0] : undefined;
 }
 function dedupeLabels(labels) {
@@ -666,9 +675,12 @@ async function visibleModeButtonLabelList(page) {
             }
             return text.includes(token);
         };
+        const scopedRoots = Array.from(document.querySelectorAll("main form, main [data-testid*='composer' i], main [class*='composer' i]"));
         return Array.from(document.querySelectorAll("button, [role='button']"))
             .map(node => {
             const element = node;
+            if (scopedRoots.length > 0 && !scopedRoots.some(root => root.contains(node)))
+                return "";
             const visibleText = (element.innerText ?? element.textContent ?? "").replace(/\s+/g, " ").trim();
             const ariaLabel = (element.getAttribute("aria-label") ?? "").replace(/\s+/g, " ").trim();
             const label = visibleText.length > 0 ? visibleText : ariaLabel;
@@ -680,7 +692,9 @@ async function visibleModeButtonLabelList(page) {
             if (visibleText.length === 0 && /feedback|conversation options|dismiss/i.test(ariaLabel))
                 return "";
             const normalized = label.toLowerCase();
-            if (!normalizedModeLabels.some(modeLabel => tokenMatches(normalized, modeLabel)))
+            const structuralModelControl = /model-switcher|model-selector|mode-selector/i.test(testId)
+                || /\b(?:gpt|sol|luna|terra)\b/i.test(label);
+            if (!structuralModelControl && !normalizedModeLabels.some(modeLabel => tokenMatches(normalized, modeLabel)))
                 return "";
             return label;
         })