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

package/dist/src/dom/wait-snapshot.d.ts

@@ -0,0 +1,43 @@
+import type { PageLike } from "../types.js";
+/**
+ * One-evaluate DOM snapshot for the messages.wait polling loop.
+ *
+ * The previous loop ran four separate DOM probes per poll and transferred the entire
+ * latest assistant text across the browser bridge every iteration, even though the loop
+ * only needs change detection until completion. This snapshot returns fixed-size text
+ * metadata (normalized length + hash + transient flag) plus generation state and
+ * response-action evidence in a single round trip, sampled atomically from the same DOM
+ * instant. The full text is fetched once, at loop exit, by the caller.
+ */
+export type WaitDomSnapshot = {
+    turnCount: number;
+    assistantTurnCount: number;
+    latestAssistantTurnIndex?: number;
+    text: WaitTextMetadata;
+    generation: {
+        active: boolean;
+        stopped: boolean;
+        signals: string[];
+    };
+    /** undefined means no conversation-turn markers were found; callers fall back to the copy-button locator. */
+    hasResponseActions?: boolean;
+};
+export type WaitTextMetadata = {
+    /** Length of the whitespace-normalized latest assistant text. */
+    length: number;
+    /** FNV-1a 32-bit hash (hex) of the whitespace-normalized latest assistant text. */
+    hash: string;
+    /** Whether the text is a transient placeholder such as "Thinking". */
+    transient: boolean;
+};
+/**
+ * SDK-side twin of the in-page metadata computation. The transient check delegates to
+ * dom/messages.ts isTransientAssistantText — the ground truth used by isResponseComplete —
+ * so only the in-page copy below is a true duplicate. The evaluate callback inlines the
+ * same normalization, hash, and transient rules because serialized callbacks cannot close
+ * over imports; `wait-snapshot.test.ts` pins the in-page copy to this helper (and thereby,
+ * transitively, to the ground truth).
+ */
+export declare function waitTextMetadata(rawText: string | undefined): WaitTextMetadata;
+export declare function fnv1a32Hex(text: string): string;
+export declare function readWaitDomSnapshot(page: PageLike): Promise<WaitDomSnapshot | undefined>;

package/dist/src/dom/wait-snapshot.js

@@ -0,0 +1,127 @@
+import { localeLabels } from "./locale-labels.js";
+import { isTransientAssistantText } from "./messages.js";
+import { normalizeWhitespace } from "./visible-text.js";
+/**
+ * SDK-side twin of the in-page metadata computation. The transient check delegates to
+ * dom/messages.ts isTransientAssistantText — the ground truth used by isResponseComplete —
+ * so only the in-page copy below is a true duplicate. The evaluate callback inlines the
+ * same normalization, hash, and transient rules because serialized callbacks cannot close
+ * over imports; `wait-snapshot.test.ts` pins the in-page copy to this helper (and thereby,
+ * transitively, to the ground truth).
+ */
+export function waitTextMetadata(rawText) {
+    const normalized = normalizeWhitespace(rawText ?? "");
+    return {
+        length: normalized.length,
+        hash: fnv1a32Hex(normalized),
+        transient: isTransientAssistantText(normalized)
+    };
+}
+export function fnv1a32Hex(text) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+export async function readWaitDomSnapshot(page) {
+    if (typeof page.evaluate !== "function") {
+        return undefined;
+    }
+    return page.evaluate((args) => {
+        const __combinedWaitSnapshot = true;
+        void __combinedWaitSnapshot;
+        const normalizeWs = (value) => value.replace(/\s+/g, " ").trim();
+        const normalizeLower = (value) => (value ?? "").trim().toLowerCase();
+        // --- Progress: turn counts and latest assistant text metadata (no text transfer) ---
+        const nodes = Array.from(document.querySelectorAll("[data-message-author-role]"));
+        const assistantNodes = nodes.filter(node => node.getAttribute("data-message-author-role") === "assistant");
+        const latestAssistant = assistantNodes.at(-1);
+        const latestAssistantTurnIndex = latestAssistant === undefined ? undefined : nodes.indexOf(latestAssistant) + 1;
+        const normalizedText = normalizeWs(latestAssistant?.innerText ?? latestAssistant?.textContent ?? "");
+        let hash = 0x811c9dc5;
+        for (let index = 0; index < normalizedText.length; index += 1) {
+            hash ^= normalizedText.charCodeAt(index);
+            hash = Math.imul(hash, 0x01000193);
+        }
+        const textHash = (hash >>> 0).toString(16).padStart(8, "0");
+        const trimmedForTransient = normalizedText.replace(/[.。…]+$/g, "").trim().toLowerCase();
+        const transient = args.transient.some(phrase => trimmedForTransient === phrase.toLowerCase())
+            || /^analyzing (?:the )?images?$/.test(trimmedForTransient)
+            || /^processing (?:the )?images?$/.test(trimmedForTransient)
+            || /^reading (?:the )?images?$/.test(trimmedForTransient);
+        // --- Generation state: mirrors dom/generation-state.ts readAssistantGenerationState ---
+        const isVisible = (element) => {
+            const style = window.getComputedStyle(element);
+            return style.display !== "none"
+                && style.visibility !== "hidden"
+                && style.opacity !== "0"
+                && element.getAttribute("aria-hidden") !== "true";
+        };
+        const visibleButtons = Array.from(document.querySelectorAll("button"))
+            .filter((button) => isVisible(button)
+            && button.disabled !== true
+            && button.getAttribute("aria-disabled") !== "true");
+        const buttonTexts = visibleButtons
+            .map(button => [
+            button.innerText,
+            button.textContent,
+            button.getAttribute("aria-label"),
+            button.getAttribute("title")
+        ].map(normalizeLower).filter(Boolean).join(" "))
+            .filter(Boolean);
+        const bodyText = normalizeLower(document.body?.innerText);
+        const haystacks = [bodyText, ...buttonTexts];
+        const matchingSignals = (phrases) => haystacks.flatMap(text => phrases
+            .map(phrase => phrase.toLowerCase())
+            .filter(phrase => text.includes(phrase)));
+        const activeSignals = matchingSignals(args.stop);
+        const stoppedSignals = matchingSignals(args.stopped);
+        const generation = {
+            active: activeSignals.length > 0,
+            stopped: stoppedSignals.length > 0,
+            signals: [...new Set([...activeSignals, ...stoppedSignals, ...buttonTexts.filter(text => /stop|cancel|stopped|answering|thinking/i.test(text))])].slice(0, 5)
+        };
+        // --- Response actions: mirrors dom/generation-state.ts latestAssistantTurnHasResponseActions ---
+        const turns = Array.from(document.querySelectorAll("[data-testid^='conversation-turn']"));
+        let hasResponseActions;
+        if (turns.length === 0) {
+            hasResponseActions = undefined;
+        }
+        else {
+            const latestTurn = [...turns].reverse().find(turn => turn.querySelector("[data-message-author-role='assistant']") !== null);
+            if (latestTurn === undefined) {
+                hasResponseActions = false;
+            }
+            else {
+                const actionText = Array.from(latestTurn.querySelectorAll("button"))
+                    .map(button => [
+                    button.innerText,
+                    button.textContent,
+                    button.getAttribute("aria-label"),
+                    button.getAttribute("title")
+                ].filter(Boolean).join(" "))
+                    .join(" ")
+                    .toLowerCase();
+                hasResponseActions = args.actions.some(phrase => actionText.includes(phrase.toLowerCase()));
+            }
+        }
+        const snapshot = {
+            turnCount: nodes.length,
+            assistantTurnCount: assistantNodes.length,
+            text: { length: normalizedText.length, hash: textHash, transient },
+            generation
+        };
+        if (latestAssistantTurnIndex !== undefined)
+            snapshot.latestAssistantTurnIndex = latestAssistantTurnIndex;
+        if (hasResponseActions !== undefined)
+            snapshot.hasResponseActions = hasResponseActions;
+        return snapshot;
+    }, {
+        transient: [...localeLabels.transientAssistant],
+        stop: [...localeLabels.stopControl],
+        stopped: [...localeLabels.stoppedAssistant],
+        actions: [...localeLabels.responseActions]
+    });
+}

package/dist/src/safety/risk.d.ts

@@ -21,6 +21,7 @@ export declare const commandRisk: {
     readonly "projects.sources.add": "medium";
     readonly "response.copy": "medium";
     readonly "modes.set": "medium";
+    readonly "modes.get": "low";
     readonly "tools.select": "medium";
     readonly "threads.delete": "high";
     readonly "threads.archive": "high";

package/dist/src/safety/risk.js

@@ -20,6 +20,7 @@ export const commandRisk = {
     "projects.sources.add": "medium",
     "response.copy": "medium",
     "modes.set": "medium",
+    "modes.get": "low",
     "tools.select": "medium",
     "threads.delete": "high",
     "threads.archive": "high",

package/dist/src/scripts/apply-intelligence-locale-captures.js

@@ -3,6 +3,14 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readLanguageCoverage } from "./locale-capture/language-coverage.js";
 const ENGLISH_MODE_LABELS = new Set(["Latest", "Instant", "Thinking", "Extended", "Medium", "High", "Extra High", "Pro"]);
+const INTELLIGENCE_MODE_OPTION_IDS = ["instant", "medium", "high", "extraHigh", "pro"];
+const ENGLISH_INTELLIGENCE_MODE_OPTIONS = {
+    instant: "Instant",
+    medium: "Medium",
+    high: "High",
+    extraHigh: "Extra High",
+    pro: "Pro",
+};
 const UPDATE_NOTE = " * Intelligence picker labels updated 2026-06-10 from a visible ChatGPT Pro session.";
 class ApplyUsageError extends Error {
     exitCode;
@@ -45,12 +53,14 @@ export async function main(argv = process.argv.slice(2)) {
             throw new ApplyUsageError(`Missing successful capture for ${language.bcp47}.`, 1);
         }
         const labels = observedNonEnglishLabels(record);
-        if (labels.length === 0)
+        const modeOptions = observedNonEnglishModeOptions(record);
+        if (labels.length === 0 && Object.keys(modeOptions).length === 0)
             continue;
         planned.push({
             locale: language.bcp47,
             file: resolve(root, "src/dom/locale", `${language.bcp47}.ts`),
             labels,
+            modeOptions,
         });
     }
     if (!options.reviewed) {
@@ -62,10 +72,10 @@ export async function main(argv = process.argv.slice(2)) {
     }
     for (const change of planned) {
         const before = await readFile(change.file, "utf8");
-        const after = mergeModeLabels(before, change.labels);
+        const after = mergeModeCapture(before, change.labels, change.modeOptions);
         if (after !== before) {
             await writeFile(change.file, after, "utf8");
-            console.log(`updated ${change.locale} labels=${change.labels.length}`);
+            console.log(`updated ${change.locale} labels=${change.labels.length} modeOptions=${Object.keys(change.modeOptions).length}`);
         }
     }
     return 0;
@@ -93,18 +103,38 @@ function observedNonEnglishLabels(record) {
     }
     return labels;
 }
-function mergeModeLabels(source, labels) {
-    let text = updateComment(source);
-    const existing = parseExistingModeLabels(text);
-    const merged = dedupe([...existing, ...labels]);
-    const line = `  modeLabels: [${merged.map(label => JSON.stringify(label)).join(", ")}],`;
-    if (/^\s*modeLabels:\s*\[[^\]]*\],/m.test(text)) {
-        return text.replace(/^\s*modeLabels:\s*\[[^\]]*\],/m, line);
+function observedNonEnglishModeOptions(record) {
+    const labels = record.intelligenceLabels ?? [];
+    if (labels.length !== INTELLIGENCE_MODE_OPTION_IDS.length) {
+        throw new ApplyUsageError(`${record.requestedLocale} has ${labels.length} Intelligence labels; expected ${INTELLIGENCE_MODE_OPTION_IDS.length}.`, 1);
     }
-    if (/^\s*copyResponse:\s*.*,\n/m.test(text)) {
-        return text.replace(/^(\s*copyResponse:\s*.*,\n)/m, `$1${line}\n`);
+    const modeOptions = {};
+    for (let index = 0; index < INTELLIGENCE_MODE_OPTION_IDS.length; index += 1) {
+        const id = INTELLIGENCE_MODE_OPTION_IDS[index];
+        const label = labels[index];
+        if (label !== ENGLISH_INTELLIGENCE_MODE_OPTIONS[id]) {
+            modeOptions[id] = [label];
+        }
     }
-    return text.replace(/^export const \w+ = \{\n/m, match => `${match}${line}\n`);
+    return modeOptions;
+}
+function mergeModeCapture(source, labels, modeOptions) {
+    let text = updateComment(source);
+    if (labels.length > 0) {
+        const existing = parseExistingModeLabels(text);
+        const merged = dedupe([...existing, ...labels]);
+        const line = `  modeLabels: [${merged.map(label => JSON.stringify(label)).join(", ")}],`;
+        if (/^\s*modeLabels:\s*\[[^\]]*\],/m.test(text)) {
+            text = text.replace(/^\s*modeLabels:\s*\[[^\]]*\],/m, line);
+        }
+        else if (/^\s*copyResponse:\s*.*,\n/m.test(text)) {
+            text = text.replace(/^(\s*copyResponse:\s*.*,\n)/m, `$1${line}\n`);
+        }
+        else {
+            text = text.replace(/^export const \w+ = \{\n/m, match => `${match}${line}\n`);
+        }
+    }
+    return mergeModeOptions(text, modeOptions);
 }
 function parseExistingModeLabels(source) {
     const match = /^\s*modeLabels:\s*\[(?<body>[^\]]*)\],/m.exec(source);
@@ -117,6 +147,62 @@ function parseExistingModeLabels(source) {
     }
     return labels;
 }
+function mergeModeOptions(source, modeOptions) {
+    const existing = parseExistingModeOptions(source);
+    const merged = {};
+    for (const id of INTELLIGENCE_MODE_OPTION_IDS) {
+        const values = dedupe([...(existing[id] ?? []), ...(modeOptions[id] ?? [])]);
+        if (values.length > 0) {
+            merged[id] = values;
+        }
+    }
+    const block = formatModeOptions(merged);
+    if (block === undefined) {
+        return source;
+    }
+    if (/^\s*modeOptions:\s*\{[\s\S]*?^\s*\},\n/m.test(source)) {
+        return source.replace(/^\s*modeOptions:\s*\{[\s\S]*?^\s*\},\n/m, `${block}\n`);
+    }
+    if (/^\s*modeLabels:\s*\[[^\]]*\],\n/m.test(source)) {
+        return source.replace(/^(\s*modeLabels:\s*\[[^\]]*\],\n)/m, `$1${block}\n`);
+    }
+    return source.replace(/^export const \w+ = \{\n/m, match => `${match}${block}\n`);
+}
+function parseExistingModeOptions(source) {
+    const options = {};
+    const blockMatch = /^\s*modeOptions:\s*\{(?<body>[\s\S]*?)^\s*\},/m.exec(source);
+    const body = blockMatch?.groups?.body;
+    if (body === undefined)
+        return options;
+    for (const id of INTELLIGENCE_MODE_OPTION_IDS) {
+        const lineMatch = new RegExp(`^\\s*${id}:\\s*\\[(?<body>[^\\]]*)\\],`, "m").exec(body);
+        const lineBody = lineMatch?.groups?.body;
+        if (lineBody === undefined)
+            continue;
+        const values = [];
+        for (const stringMatch of lineBody.matchAll(/"((?:\\"|[^"])*)"/g)) {
+            values.push(JSON.parse(`"${stringMatch[1]}"`));
+        }
+        if (values.length > 0) {
+            options[id] = values;
+        }
+    }
+    return options;
+}
+function formatModeOptions(modeOptions) {
+    const lines = INTELLIGENCE_MODE_OPTION_IDS
+        .map(id => {
+        const values = modeOptions[id];
+        return values === undefined || values.length === 0
+            ? undefined
+            : `    ${id}: [${values.map(value => JSON.stringify(value)).join(", ")}],`;
+    })
+        .filter((line) => line !== undefined);
+    if (lines.length === 0) {
+        return undefined;
+    }
+    return ["  modeOptions: {", ...lines, "  },"].join("\n");
+}
 function updateComment(source) {
     let text = source.replace(/\n \* Omitted because they match English case-insensitively: `modeLabels`[\s\S]*?blocker copy\.\n/g, "\n * Some non-Intelligence surfaces may still fall back to English + `selector_drift`.\n");
     if (!text.includes(UPDATE_NOTE)) {

package/dist/src/types.d.ts

@@ -183,10 +183,14 @@ export type WaitArgs = {
     stableMs?: number;
     pollMs?: number;
     mode?: "normal" | "deep_research";
+    responseContent?: "include" | "metadata";
 };
 export type WaitData = {
     complete: boolean;
     responseText?: string;
+    responseChars?: number;
+    responseSha256?: string;
+    responseContent?: "include" | "metadata";
     assistantTurnCount: number;
     elapsedMs: number;
 };
@@ -291,6 +295,8 @@ export type AskReadData = {
 export type AttachFilesArgs = {
     paths: string[];
     timeoutMs?: number;
+    includeDiagnostics?: boolean;
+    includeHashes?: boolean;
 };
 export type AttachedFile = {
     path: string;
@@ -302,11 +308,13 @@ export type FilePreflightArgs = {
     paths: string[];
     maxBytesPerFile?: number;
     maxTotalBytes?: number;
+    includeHashes?: boolean;
 };
 export type FilePreflightFile = AttachedFile & {
     extension: string;
     mimeType: string;
     category: FileCategory;
+    sha256?: string;
 };
 export type FilePreflightData = {
     files: FilePreflightFile[];
@@ -314,6 +322,20 @@ export type FilePreflightData = {
 };
 export type AttachFilesData = {
     files: AttachedFile[];
+    diagnostics?: FileUploadDiagnostics;
+};
+export type BrowserInputFileDiagnostic = {
+    name: string;
+    size: number;
+    type?: string;
+    lastModified?: number;
+};
+export type BrowserInputDiagnostic = {
+    files: BrowserInputFileDiagnostic[];
+};
+export type FileUploadDiagnostics = {
+    preflight: FilePreflightData;
+    browserInput?: BrowserInputDiagnostic;
 };
 export type ProjectSourceStatus = "ready" | "processing" | "failed" | "unknown";
 export type ProjectSource = {
@@ -460,6 +482,12 @@ export type SetModeArgs = {
     version?: string;
     timeoutMs?: number;
 };
+export type GetModeArgs = {
+    timeoutMs?: number;
+};
+export type GetModeData = {
+    modes: string[];
+};
 export type SelectToolArgs = {
     tool: "web_search" | "deep_research" | "create_image" | string;
     timeoutMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-chatgpt-control",
-  "version": "0.2.0-alpha.1",
+  "version": "0.3.0-alpha.1",
   "description": "Unofficial SDK for Codex agents controlling visible ChatGPT web sessions.",
   "type": "module",
   "license": "MIT",
@@ -74,7 +74,7 @@
   "devDependencies": {
     "@types/node": "^24.13.1",
     "ajv": "^8.17.1",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "tsx": "^4.20.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.8"

package/references/backend-protocol.md

@@ -67,7 +67,7 @@ Current protocol error codes are:
 
 Browser-control blockers are not protocol errors. They are normal command or runner results with `status: "blocked"`, `status: "partial"`, or `status: "needs_confirmation"` plus blocker/interruption details.
 
-`status: "partial"` is the required result for incomplete response capture. A partial result may still include `output_text` and `data.responseText`, but consumers must treat that text as incomplete until a later wait confirms completion. Common causes are wait timeout after partial assistant text, active generation controls such as `Stop answering`, stopped-generation markers such as `Stopped thinking`, or a read fallback after the wait step could not confirm completion. Intentional capture clipping uses `data.captureLimit` plus warnings; it is separate from ChatGPT generation length.
+`status: "partial"` is the required result for incomplete response capture. A partial result may still include `output_text` and `data.responseText`, but consumers must treat that text as incomplete until a later wait confirms completion. Common causes are wait timeout after partial assistant text, active generation controls such as `Stop answering`, stopped-generation markers such as `Stopped thinking`, or a read fallback after the wait step could not confirm completion. For status-only polling, `messages.wait` accepts `responseContent: "metadata"`; partial and completed wait results then omit assistant text and instead return compact metadata such as `data.responseChars` and `data.responseSha256`. Intentional capture clipping uses `data.captureLimit` plus warnings; it is separate from ChatGPT generation length.
 
 ## Streaming
 
@@ -112,7 +112,7 @@ The backend must support:
 - diagnostics: `doctor`
 - reports: `createReport`, `reports.create`, `reports.redact`, `reports.summarize`
 - command discovery: `commands`, `describe`, `help`
-- primitives: `session.bootstrap`, `threads.*`, `messages.*`, `artifacts.*`, `files.preflight`, `files.attach`, `files.downloadLatest`, `projects.sources.list`, `projects.sources.planAdd`, `projects.sources.add`, `modes.set`, `tools.select`, `response.copy`
+- primitives: `session.bootstrap`, `threads.*`, `messages.*`, `artifacts.*`, `files.preflight`, `files.attach`, `files.downloadLatest`, `projects.sources.list`, `projects.sources.planAdd`, `projects.sources.add`, `modes.set`, `modes.get`, `tools.select`, `response.copy`
 
 `doctor` returns a normal `CommandResult` whose `data.checks` map is extensible. Scenario checks such as `existing_tab`, `artifacts`, `file_preflight`, `localization`, and `reports` may add optional `code`, `blockerKind`, `nextCommand`, and JSON `details` fields to individual check entries while preserving the existing `status`, `message`, and `remediation` fields.
 
@@ -120,7 +120,9 @@ The backend must support:
 
 Attachment paths are interpreted on the machine running the Node backend. Use an absolute path in that host operating system's native form. On macOS/Linux/WSL, use paths such as `/example/user/file.pdf`, `/home/you/file.pdf`, or `/mnt/c/example/user/file.pdf`. On Windows backend hosts, use fully qualified paths such as `C:\Users\you\file.pdf` or UNC paths such as `\\server\share\file.pdf`. Drive-relative paths like `C:Users\you\file.pdf`, root-relative paths like `\tmp\file.pdf`, and Windows-looking paths sent to a POSIX backend are rejected before filesystem access.
 
-Use `files.preflight` for non-mutating local validation before browser upload workflows. It validates absolute paths, existence, readability, file-vs-directory status, configurable per-file and total byte limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses. It does not open ChatGPT, perform a live upload, or read file contents for MIME detection. `askWithFiles` and `files.attach` run the same preflight before upload attempts so obvious local file failures stop before browser interaction.
+Use `files.preflight` for non-mutating local validation before browser upload workflows. It validates absolute paths, existence, readability, file-vs-directory status, configurable per-file and total byte limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses. Zero-byte files are blocked before browser interaction because ChatGPT rejects empty attachments. By default the command does not open ChatGPT, perform a live upload, read file contents for MIME detection, or return file-content fingerprints. Callers may pass `includeHashes: true` to include SHA-256 metadata for local diagnostics; file contents are never returned. `askWithFiles` and `files.attach` run the same preflight before upload attempts so obvious local file failures stop before browser interaction.
+
+`files.attach` accepts `includeDiagnostics: true` to return metadata-only upload diagnostics in `data.diagnostics`: the preflight result plus the browser input's selected file names and sizes when the DOM exposes them. Pair `includeDiagnostics: true` with `includeHashes: true` when diagnosing whether a non-empty local file became an empty browser-side `File`; do not persist these diagnostics in public reports unless the user has approved content fingerprint metadata.
 
 ## Project Sources
 
@@ -213,7 +215,7 @@ Important: in Codex, `globalThis.agent` is not present until the Chrome plugin r
 The live Chrome bootstrap is:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```

package/references/localization.md

@@ -77,7 +77,8 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 | `projectSourcesTab` / `projectSourcesAddSource` / `projectSourcesUploadFiles` | Project Sources tab and append-add flow | visible tab/button/menu text |
 | `copyResponse` | copy-response button | `aria-label` |
 | `download` / `downloadImage` / `imageContainerHint` | download affordances | `aria-label` / container hint |
-| `modeLabels` / `modeOpenerExtra` | model/effort switcher | visible button + menu text |
+| `modeLabels` / `modeOpenerExtra` | model/effort switcher recognition and openers | visible button + menu text |
+| `modeOptions.<semantic-id>` | selectable model/intelligence mode options | visible picker rows, keyed by stable ids such as `high`, `extraHigh`, and `pro` |
 | `tools.web_search` / `tools.deep_research` / `tools.create_image` | tool menu items | visible menu text |
 | `signedInMarkers` | signed-in detection | sidebar/shell words |
 | `transientAssistant` | streaming placeholder filter | assistant streaming text ("Thinking", etc.) |
@@ -141,7 +142,13 @@ import type { LocaleContribution } from "./types.js";
 
 export const de = {
   sendButton: ["Nachricht senden"],
-  modeLabels: ["Neueste", "Schnell", "Denken", "Erweitert", "Pro"],
+  modeLabels: ["Sofort", "Mittel", "Hoch", "Extra hoch"],
+  modeOptions: {
+    instant: ["Sofort"],
+    medium: ["Mittel"],
+    high: ["Hoch"],
+    extraHigh: ["Extra hoch"],
+  },
   tools: {
     web_search: ["Websuche"],
   },
@@ -150,11 +157,14 @@ export const de = {
 ```
 
 Leave the canonical English first (it comes from `en.ts`), and leave the API keys
-(`web_search`, the `effort` values) unchanged.
+(`web_search`, `modeOptions.pro`, `modeOptions.high`, and the other semantic ids)
+unchanged.
 
 Newer ChatGPT rollouts may expose `Medium`, `High`, `Extra High`, and `Pro`
 under an `Intelligence` picker. Add localized equivalents only after observing
-those exact labels in the target locale.
+those exact labels in the target locale. Put broad picker/opening labels in
+`modeLabels`, but put selectable labels under `modeOptions.<semantic-id>` so
+short labels such as `Pro` cannot match unrelated rows like `Move to project`.
 
 Then open [`src/dom/locale/index.ts`](../src/dom/locale/index.ts) and register the new
 locale:

package/references/python-parity.md

@@ -29,6 +29,8 @@ Wire fields stay TypeScript-compatible. Python exposes idiomatic aliases:
 
 Incomplete response capture is also shared contract behavior. Python must preserve `status == "partial"`, `output_text`, warnings, and any nested `data.captureLimit` dictionaries exactly as the TypeScript backend returns them. `partial` is not a protocol error: callers should inspect `data.complete` and run another wait/read on the same thread when they need final output.
 
+For long-answer polling, Python forwards `response_content="metadata"` to the shared wire field `responseContent: "metadata"` on `messages.wait`. The TypeScript backend then omits assistant text from wait results and returns compact metadata such as `data.responseChars` and `data.responseSha256`; Python must preserve those fields without trying to reconstruct omitted content.
+
 Generated-image behavior stays owned by the TypeScript runtime. Python exposes
 the same backend commands through `chatgpt.artifacts.list_latest(...)`,
 `chatgpt.artifacts.wait(...)`, and `chatgpt.artifacts.download_latest(...)`.
@@ -49,7 +51,7 @@ the shared `blocker-explanation-profiles.json` and
 
 Python does not reinterpret attachment paths. It sends the path string to the Node backend, and the backend validates the path against its own host operating system. Attachment paths must be absolute on the backend host. On macOS/Linux/WSL backends, use POSIX paths such as `/example/user/file.pdf` or `/mnt/c/example/user/file.pdf`. On Windows backends, use fully qualified paths such as `C:\Users\you\file.pdf` or UNC paths such as `\\server\share\file.pdf`. Drive-relative paths, root-relative paths, and Windows-looking paths sent to a POSIX backend are rejected before filesystem access.
 
-Python exposes the backend-visible `files.preflight` command as `chatgpt.files.preflight(...)`. It returns the same `CommandResult` as TypeScript and can be decoded with `FilePreflightData` when callers want typed metadata. The command validates paths, readability, file-vs-directory status, size limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT or reading file contents for MIME detection.
+Python exposes the backend-visible `files.preflight` command as `chatgpt.files.preflight(...)`. It returns the same `CommandResult` as TypeScript and can be decoded with `FilePreflightData` when callers want typed metadata. The command validates paths, readability, file-vs-directory status, size limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT or reading file contents for MIME detection. Zero-byte files are blocked before browser interaction. Optional `include_hashes=True` / wire `includeHashes: true` adds SHA-256 metadata to `FilePreflightFile.sha256` for local diagnostics; file contents are never returned.
 
 ## Project Sources
 
@@ -161,7 +163,7 @@ Python is a native SDK facade over the local backend protocol. The initial brows
 
 - `dist/codex-chatgpt-control-backend.mjs` is the stdio backend bundle.
 - `BackendClient` and `StdioBackendTransport` keep Python backend calls long-lived.
-- `NodeSidecarTransport.run(...)` remains as a compatibility wrapper over backend `runner.run`.
+- `NodeSidecarTransport.run(...)` remains as a compatibility wrapper over backend `runner.run`. By default each call spawns and tears down its own backend subprocess; use it as a context manager (or call `open()`/`close()`) to reuse one persistent backend process across calls in multi-command workflows. Transport-level failures close the persistent session; protocol-level errors keep it open.
 - Ordinary-shell smoke passes when browser-required calls return structured `browser_bridge_unavailable`.
 - Browser-bridge runtime smoke remains explicitly gated because it can operate a real ChatGPT session.
 
@@ -199,7 +201,7 @@ python scripts/live_smoke.py --mode browser-bridge
 When the live backend is hosted inside the Codex Chrome plugin runtime, do not test bridge availability from a normal shell or an unbootstrapped Node REPL. First initialize the Chrome runtime:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```

package/references/troubleshooting.md

@@ -33,7 +33,7 @@ Use `chatgpt.explainBlocker(result)` or Python `explain_blocker(result)` when re
 Do not conclude that Chrome or the extension is broken from a plain shell result, or from checking `globalThis.agent` before the Chrome plugin runtime is initialized. For a true Codex Chrome-plugin live run, bootstrap the runtime first:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```
@@ -90,9 +90,24 @@ Agent-facing remediation text should name both settings:
 
 Attachment paths are validated against the backend host's operating system. If a Windows-looking path is rejected on macOS/Linux, do not retry with the same string. Convert it to the backend host's real path, for example `/mnt/c/example/user/file.pdf` for a WSL/Linux backend. Drive-relative paths like `C:Users\you\file.pdf`, root-relative paths like `\tmp\file.pdf`, and empty or relative paths are always rejected.
 
+## Empty Or Stripped Attachments
+
+Zero-byte files are blocked by `files.preflight` before browser upload because
+ChatGPT rejects empty attachments with a generic help-center error. If a user
+reports that manual upload works but automated upload fails, compare local and
+browser-side metadata instead of guessing:
+
+1. Run `files.preflight({ paths, includeHashes: true })` and inspect `bytes`
+   plus `sha256` for the backend-visible file.
+2. Run `files.attach({ paths, includeDiagnostics: true, includeHashes: true })`
+   and inspect `data.diagnostics.browserInput.files[].size` when available.
+3. If preflight `bytes` is zero, investigate the source path, generation race,
+   cloud placeholder, or host/container path mapping. If preflight bytes are
+   nonzero but browser-side size is zero, investigate the Chrome handoff.
+
 ## Clipboard Unavailable
 
-`response.copy` falls back to DOM text extraction when the macOS system clipboard does not change.
+`response.copy` falls back to DOM text extraction when the system clipboard does not change. Clipboard reads use `pbpaste` on macOS, PowerShell `Get-Clipboard` on Windows, and `xclip`/`xsel`/`wl-paste` on Linux; hosts without any of these tools always use the DOM fallback.
 
 ## Flattened Or Unreadable Response Capture
 
@@ -100,12 +115,20 @@ Use `readLatest({ format: "markdown" })`, `copyLatest()`, or the default SDK `re
 
 ## Long Responses Return `partial`
 
-Long Pro, Thinking, Deep Research, or file-backed answers can take longer than the default wait window. Treat `status: "partial"` and `data.complete: false` as an incomplete capture even when `output_text` is non-empty. Re-run `messages.wait(...)` on the same thread with a larger timeout, then call `readLatest(...)` or `copyLatest(...)` only after completion is confirmed.
+Long Pro, Thinking, Deep Research, or file-backed answers can take longer than the default wait window. Treat `status: "partial"` and `data.complete: false` as an incomplete capture even when `output_text` is non-empty. For repeated polling, prefer `messages.wait({ responseContent: "metadata", ... })` so Codex receives compact status metadata instead of the same growing partial answer body. Re-run `messages.wait(...)` on the same thread until completion is confirmed, then call `readLatest(...)` or `copyLatest(...)` once.
 
 Recommended long-answer wait:
 
 ```ts
-wait: { timeoutMs: 600000, stableMs: 8000, pollMs: 1000 }
+await chatgpt.messages.wait({
+  timeoutMs: 45_000,
+  stableMs: 2_000,
+  pollMs: 1_000,
+  mode: "deep_research",
+  responseContent: "metadata"
+});
+
+const final = await chatgpt.messages.readLatest({ format: "markdown" });
 ```
 
 Active generation may appear as a visible or accessible-name control such as `Stop answering`, `Stop generating`, or `Stop streaming`. Stopped generation may appear as `Stopped thinking`. Treat all of those as incomplete states.
@@ -144,6 +167,6 @@ Doctor also supports opt-in scenario checks:
 
 - `existing_tab`: claims only the requested already-open tab target by default and reports `existing_tab_not_found` / `existing_tab_ambiguous` diagnostics without opening a replacement tab unless `existingTab.ifMissing` explicitly allows that.
 - `artifacts`: verifies current-page artifact selector/download/asset support without requesting generation.
-- `file_preflight`: validates supplied local file paths without opening ChatGPT or attempting upload. It reports path count, total bytes, duplicate/zero-byte warnings, and extension-based MIME/category metadata; fatal local file problems map to the same structured blockers as `files.preflight`.
+- `file_preflight`: validates supplied local file paths without opening ChatGPT or attempting upload. It reports path count, total bytes, duplicate warnings, zero-byte blockers, and extension-based MIME/category metadata; fatal local file problems map to the same structured blockers as `files.preflight`.
 - `localization`: checks locale-label registry readiness and English canonical labels without changing the ChatGPT account language; it is not yet proof of full localized selector coverage.
 - `reports`: checks redacted-report policy and existing destination writability when possible without writing a report.