codex-chatgpt-control 0.5.1-alpha.2 → 0.5.1-alpha.4

package/dist/src/backend/stdio-server.js

@@ -1,31 +1,111 @@
-import { createInterface } from "node:readline";
+import { TextDecoder } from "node:util";
 import { BackendSession } from "./session.js";
-import { backendResponseError, parseBackendRequest, ProtocolError } from "./protocol.js";
+import { backendResponseError, BACKEND_NDJSON_FRAME_LIMIT_BYTES, isValidBackendRequestId, parseBackendRequest, ProtocolError } from "./protocol.js";
+const DEFAULT_BACKEND_SERVER_MAX_IN_FLIGHT = 256;
+const MAX_BACKEND_SERVER_IN_FLIGHT = 10_000;
 export async function runBackendStdioServer(options) {
-    const session = options.session ?? new BackendSession();
-    const lines = createInterface({
-        input: options.input,
-        crlfDelay: Infinity
+    validateServerOptions(options);
+    const session = options.session ?? new BackendSession(options.backendIdentity === undefined ? {} : { backendIdentity: options.backendIdentity });
+    const frameLimitBytes = options.frameLimitBytes ?? BACKEND_NDJSON_FRAME_LIMIT_BYTES;
+    const maxInFlight = options.maxInFlight ?? DEFAULT_BACKEND_SERVER_MAX_IN_FLIGHT;
+    let outputUnavailable = false;
+    let correlationViolation = false;
+    const writeJson = createJsonLineWriter(options.output, frameLimitBytes, () => {
+        outputUnavailable = true;
+        // A failed output route cannot safely correlate any later response. Stop
+        // reading as soon as the writer detects the failure; the final cleanup
+        // below closes the output after already-admitted routes settle.
+        options.input.destroy();
     });
-    const writeJson = createJsonLineWriter(options.output);
+    const failClosedOnCorrelationViolation = () => {
+        if (correlationViolation)
+            return;
+        correlationViolation = true;
+        // A duplicate active requestId has no safe response route: either caller
+        // could observe a frame carrying that id. Stop admitting new input, but
+        // leave the already-admitted route alive so its sole terminal response
+        // can still settle without being preempted by the duplicate.
+        options.input.destroy();
+    };
+    const activeRequestIds = new Set();
     const tasks = new Set();
-    for await (const line of lines) {
-        const trimmed = line.trim();
-        if (trimmed.length === 0)
-            continue;
-        const task = handleLine(session, trimmed, writeJson, options.error);
-        tasks.add(task);
-        void task.finally(() => {
-            tasks.delete(task);
-        }).catch(() => { });
+    try {
+        for await (const line of readBoundedNdjsonLines(options.input, frameLimitBytes)) {
+            if (outputUnavailable || correlationViolation || !writeJson.isUsable())
+                break;
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            // Check the bounded, already-framed requestId before waiting for an
+            // in-flight slot. Otherwise maxInFlight=1 can turn an active duplicate
+            // into an apparently valid sequential reuse after the first route
+            // settles.
+            const preflightRequestId = requestIdFromLine(trimmed);
+            if (preflightRequestId !== undefined && activeRequestIds.has(preflightRequestId)) {
+                failClosedOnCorrelationViolation();
+                break;
+            }
+            while (tasks.size >= maxInFlight)
+                await waitForTaskSlot(tasks);
+            if (outputUnavailable || correlationViolation || !writeJson.isUsable())
+                break;
+            const task = handleLine(session, trimmed, writeJson, options.error, activeRequestIds, failClosedOnCorrelationViolation);
+            tasks.add(task);
+            void task.finally(() => {
+                tasks.delete(task);
+            }).catch(() => { });
+        }
+    }
+    catch (caught) {
+        if (caught instanceof BackendFrameError) {
+            // Once framing is untrusted, no later request can be correlated safely.
+            // Close the owned input/output routes so an embedding cannot continue
+            // using a partially consumed sidecar.
+            options.input.destroy();
+            options.output.end();
+        }
+        if (!correlationViolation) {
+            await writeDiagnostic(options.error, caught instanceof BackendFrameError
+                ? new Error(caught.message)
+                : caught);
+        }
+    }
+    const settled = await Promise.allSettled(tasks);
+    const fatalOutput = settled.find(result => result.status === "rejected"
+        && result.reason instanceof BackendFrameError);
+    if (correlationViolation || fatalOutput?.status === "rejected") {
+        options.input.destroy();
+        options.output.end();
     }
-    await Promise.allSettled(tasks);
 }
-async function handleLine(session, line, writeJson, error) {
+async function handleLine(session, line, writeJson, error, activeRequestIds, failClosedOnCorrelationViolation) {
     let request;
+    let registeredRequestId;
     try {
         const raw = JSON.parse(line);
+        const rawRequestId = isRecord(raw) && isValidBackendRequestId(raw.requestId)
+            ? raw.requestId
+            : undefined;
+        if (rawRequestId !== undefined && activeRequestIds.has(rawRequestId)) {
+            // Check before protocol parsing too: a malformed duplicate must not
+            // fall through to the generic error path and reuse the active id.
+            failClosedOnCorrelationViolation();
+            return;
+        }
         request = parseBackendRequest(raw);
+        if (!writeJson.isUsable())
+            return;
+        if (request.requestId !== undefined) {
+            if (activeRequestIds.has(request.requestId)) {
+                // Never send an error carrying this id: it belongs to the route that
+                // was admitted first, and a duplicate response would settle that
+                // original caller as if its own route had failed.
+                failClosedOnCorrelationViolation();
+                return;
+            }
+            activeRequestIds.add(request.requestId);
+            registeredRequestId = request.requestId;
+        }
         if (request.command === "runner.stream") {
             for await (const event of session.stream(request)) {
                 await writeJson(event);
@@ -35,16 +115,22 @@ async function handleLine(session, line, writeJson, error) {
         await writeJson(await session.dispatch(request));
     }
     catch (caught) {
+        if (caught instanceof BackendFrameError)
+            throw caught;
         const response = backendResponseError(request?.requestId ?? requestIdFromLine(line), normalizeError(caught));
         await writeJson(response);
         if (!(caught instanceof ProtocolError)) {
             await writeDiagnostic(error, caught);
         }
     }
+    finally {
+        if (registeredRequestId !== undefined)
+            activeRequestIds.delete(registeredRequestId);
+    }
 }
 function normalizeError(error) {
     if (error instanceof SyntaxError) {
-        return new ProtocolError("invalid_request", `Invalid JSON backend request line: ${error.message}`, false);
+        return new ProtocolError("invalid_request", "Invalid JSON backend request line.", false);
     }
     if (error instanceof Error)
         return error;
@@ -53,7 +139,7 @@ function normalizeError(error) {
 function requestIdFromLine(line) {
     try {
         const parsed = JSON.parse(line);
-        if (isRecord(parsed) && typeof parsed.requestId === "string" && parsed.requestId.length > 0) {
+        if (isRecord(parsed) && isValidBackendRequestId(parsed.requestId)) {
             return parsed.requestId;
         }
     }
@@ -62,27 +148,153 @@ function requestIdFromLine(line) {
     }
     return undefined;
 }
-function createJsonLineWriter(output) {
+function createJsonLineWriter(output, frameLimitBytes, onFatal) {
     let tail = Promise.resolve();
-    return value => {
-        const next = tail.then(() => writeLine(output, JSON.stringify(value)));
+    let usable = true;
+    let fatalNotified = false;
+    const markFatal = () => {
+        usable = false;
+        if (fatalNotified)
+            return;
+        fatalNotified = true;
+        onFatal();
+    };
+    const writeJson = (value) => {
+        const next = tail.then(() => {
+            if (!usable) {
+                throw new BackendFrameError("backend_invalid_output", "Backend output is unavailable.");
+            }
+            let line;
+            try {
+                const encoded = JSON.stringify(value);
+                if (typeof encoded !== "string") {
+                    throw new Error("JSON.stringify returned no value.");
+                }
+                line = encoded;
+            }
+            catch {
+                const frameError = new BackendFrameError("backend_invalid_output", "Backend response could not be encoded as JSON.");
+                markFatal();
+                throw frameError;
+            }
+            // The shared limit is the encoded JSON frame, excluding its NDJSON
+            // delimiter.  Keep server output symmetric with both readers.
+            if (Buffer.byteLength(line, "utf8") > frameLimitBytes) {
+                const frameError = new BackendFrameError("backend_frame_too_large", `Backend output frame exceeds the ${frameLimitBytes} byte limit.`);
+                markFatal();
+                throw frameError;
+            }
+            return writeLine(output, `${line}\n`).catch(() => {
+                const frameError = new BackendFrameError("backend_invalid_output", "Backend output could not be written.");
+                markFatal();
+                throw frameError;
+            });
+        });
         tail = next.catch(() => { });
         return next;
     };
+    writeJson.isUsable = () => usable;
+    return writeJson;
 }
 async function writeDiagnostic(error, value) {
     if (error === undefined)
         return;
     const message = value instanceof Error ? `${value.name}: ${value.message}` : String(value);
-    await writeLine(error, message);
+    await writeLine(error, `${message}\n`);
 }
 async function writeLine(output, line) {
-    if (output.write(`${line}\n`))
-        return;
-    await new Promise(resolve => {
-        output.once("drain", resolve);
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            output.off("error", onError);
+            if (error !== undefined && error !== null)
+                reject(error);
+            else
+                resolve();
+        };
+        const onError = (error) => finish(error);
+        output.once("error", onError);
+        try {
+            output.write(line, error => finish(error));
+        }
+        catch (error) {
+            finish(error instanceof Error ? error : new Error(String(error)));
+        }
     });
 }
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+async function waitForTaskSlot(tasks) {
+    await Promise.race([...tasks].map(task => task.then(() => undefined, () => undefined)));
+}
+class BackendFrameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "BackendFrameError";
+    }
+}
+async function* readBoundedNdjsonLines(input, limitBytes) {
+    let frameBuffer = Buffer.alloc(0);
+    let frameBytes = 0;
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for await (const chunk of input) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+        let offset = 0;
+        while (offset < bytes.length) {
+            const newlineIndex = bytes.indexOf(0x0a, offset);
+            const segmentEnd = newlineIndex >= 0 ? newlineIndex : bytes.length;
+            const segment = bytes.subarray(offset, segmentEnd);
+            if (segment.length > 0) {
+                const nextFrameBytes = frameBytes + segment.length;
+                if (nextFrameBytes > limitBytes) {
+                    throw new BackendFrameError("backend_frame_too_large", `Backend input frame exceeds the ${limitBytes} byte limit.`);
+                }
+                if (nextFrameBytes > frameBuffer.length) {
+                    let nextCapacity = Math.max(frameBuffer.length, 1);
+                    while (nextCapacity < nextFrameBytes) {
+                        nextCapacity = Math.min(limitBytes, nextCapacity * 2);
+                    }
+                    const grown = Buffer.allocUnsafe(nextCapacity);
+                    frameBuffer.copy(grown, 0, 0, frameBytes);
+                    frameBuffer = grown;
+                }
+                segment.copy(frameBuffer, frameBytes);
+                frameBytes = nextFrameBytes;
+            }
+            if (newlineIndex < 0)
+                break;
+            const frame = frameBuffer.subarray(0, frameBytes);
+            const body = frame.length > 0 && frame[frame.length - 1] === 0x0d
+                ? frame.subarray(0, frame.length - 1)
+                : frame;
+            try {
+                yield decoder.decode(body);
+            }
+            catch {
+                throw new BackendFrameError("backend_invalid_encoding", "Backend input contained invalid UTF-8.");
+            }
+            frameBytes = 0;
+            offset = newlineIndex + 1;
+        }
+    }
+    if (frameBytes > 0) {
+        throw new BackendFrameError("backend_unterminated_frame", "Backend input ended with an unterminated NDJSON frame.");
+    }
+}
+function validateServerOptions(options) {
+    for (const [name, value] of [
+        ["maxInFlight", options.maxInFlight],
+        ["frameLimitBytes", options.frameLimitBytes]
+    ]) {
+        const max = name === "frameLimitBytes" ? BACKEND_NDJSON_FRAME_LIMIT_BYTES : MAX_BACKEND_SERVER_IN_FLIGHT;
+        if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0 || value > max)) {
+            throw new TypeError(`Backend stdio option ${name} must be a positive safe integer.`);
+        }
+    }
+}

package/dist/src/browser/active-composer-file-input.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fixed CDP expression for one trusted user gesture on the unique file input
+ * owned by the unique visible ChatGPT composer. Local paths never enter this
+ * expression; the sanctioned file-chooser capability performs the handoff.
+ *
+ * Keep this shared by the ordinary files command and the transactional
+ * attachment provider so their target-selection safety contract cannot drift.
+ */
+export declare const ACTIVE_COMPOSER_FILE_INPUT_CLICK_EXPRESSION = "(() => {\n  const visible = element => {\n    if (element.hidden || element.closest(\"[hidden], [inert], [aria-hidden='true']\")) return false;\n    const style = getComputedStyle(element);\n    const rect = element.getBoundingClientRect();\n    return style.display !== \"none\" && style.visibility !== \"hidden\" && style.opacity !== \"0\"\n      && (rect.width > 0 || rect.height > 0);\n  };\n  const textboxes = [...document.querySelectorAll(\"textarea, [contenteditable='true'], [role='textbox']\")].filter(visible);\n  const composers = [...new Set(textboxes.map(textbox =>\n    textbox.closest(\"form\")\n      ?? textbox.closest(\"[data-testid*='composer' i]\")\n      ?? textbox.closest(\"[aria-label*='composer' i]\")\n      ?? textbox.closest(\"[class*='composer' i]\")\n  ).filter(Boolean))];\n  if (composers.length !== 1) return { ok: false, reason: \"active composer was not unique\" };\n  const all = [...composers[0].querySelectorAll(\"input[type='file']\")]\n    .filter(input => !input.disabled && input.getAttribute(\"aria-disabled\") !== \"true\");\n  const preferred = all.filter(input => input.id === \"upload-files\");\n  const nonImage = all.filter(input => input.getAttribute(\"accept\") !== \"image/*\");\n  const candidates = preferred.length ? preferred : nonImage.length ? nonImage : all;\n  if (candidates.length !== 1) return { ok: false, reason: \"active composer file input was not unique\" };\n  candidates[0].click();\n  return { ok: true };\n})()";

package/dist/src/browser/active-composer-file-input.js

@@ -0,0 +1,33 @@
+/**
+ * Fixed CDP expression for one trusted user gesture on the unique file input
+ * owned by the unique visible ChatGPT composer. Local paths never enter this
+ * expression; the sanctioned file-chooser capability performs the handoff.
+ *
+ * Keep this shared by the ordinary files command and the transactional
+ * attachment provider so their target-selection safety contract cannot drift.
+ */
+export const ACTIVE_COMPOSER_FILE_INPUT_CLICK_EXPRESSION = `(() => {
+  const visible = element => {
+    if (element.hidden || element.closest("[hidden], [inert], [aria-hidden='true']")) return false;
+    const style = getComputedStyle(element);
+    const rect = element.getBoundingClientRect();
+    return style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0"
+      && (rect.width > 0 || rect.height > 0);
+  };
+  const textboxes = [...document.querySelectorAll("textarea, [contenteditable='true'], [role='textbox']")].filter(visible);
+  const composers = [...new Set(textboxes.map(textbox =>
+    textbox.closest("form")
+      ?? textbox.closest("[data-testid*='composer' i]")
+      ?? textbox.closest("[aria-label*='composer' i]")
+      ?? textbox.closest("[class*='composer' i]")
+  ).filter(Boolean))];
+  if (composers.length !== 1) return { ok: false, reason: "active composer was not unique" };
+  const all = [...composers[0].querySelectorAll("input[type='file']")]
+    .filter(input => !input.disabled && input.getAttribute("aria-disabled") !== "true");
+  const preferred = all.filter(input => input.id === "upload-files");
+  const nonImage = all.filter(input => input.getAttribute("accept") !== "image/*");
+  const candidates = preferred.length ? preferred : nonImage.length ? nonImage : all;
+  if (candidates.length !== 1) return { ok: false, reason: "active composer file input was not unique" };
+  candidates[0].click();
+  return { ok: true };
+})()`;

package/dist/src/browser/attach.d.ts

@@ -1,10 +1,13 @@
 import type { BootstrapArgs, BrowserLike, PageLike, RuntimeEnv } from "../types.js";
+import { type CoordinatedBrowserOptions } from "../runtime/coordinated-browser.js";
 export type AttachedBrowser = {
     browser: BrowserLike;
     page: PageLike;
     browserName: string;
     tabId?: string;
 };
-export declare function attachChatGPTBrowser(env: RuntimeEnv, args?: BootstrapArgs): Promise<AttachedBrowser>;
+export declare function attachChatGPTBrowser(env: RuntimeEnv, args?: BootstrapArgs, coordination?: CoordinatedBrowserOptions): Promise<AttachedBrowser>;
+/** Resolve the configured provider browser without selecting, claiming, or creating a tab. */
+export declare function resolveChatGPTBrowser(env: RuntimeEnv, coordination?: CoordinatedBrowserOptions): Promise<BrowserLike>;
 export { isChatGPTUrl } from "./chatgpt-url.js";
 export declare function tabIdFromPage(page: PageLike): string | undefined;

package/dist/src/browser/attach.js

@@ -1,11 +1,13 @@
 import { BrowserBridgeUnavailableError, ChatGPTControlError, LoginRequiredError } from "../errors.js";
 import { CHATGPT_HOME, isChatGPTUrl } from "./chatgpt-url.js";
 import { parseConversationId, readPageState } from "./page-state.js";
+import { createCoordinatedBrowser, createCoordinatedPageForBrowser } from "../runtime/coordinated-browser.js";
+import { unwrapCoordinatedPage } from "../runtime/coordinated-page.js";
 const MAX_EXISTING_TAB_DIAGNOSTIC_CANDIDATES = 10;
 const MAX_EXISTING_TAB_DIAGNOSTIC_FIELD_LENGTH = 240;
-export async function attachChatGPTBrowser(env, args = {}) {
-    const browser = await getBrowser(env);
-    const page = await getOrCreateChatGPTPage(browser, env, args);
+export async function attachChatGPTBrowser(env, args = {}, coordination) {
+    const browser = await getBrowser(env, coordination);
+    const page = await getOrCreateChatGPTPage(browser, env, args, coordination);
     await assertPageOnChatGPTOrigin(page);
     const state = await readPageState(page);
     if (!isChatGPTUrl(state.url))
@@ -24,9 +26,13 @@ export async function attachChatGPTBrowser(env, args = {}) {
     }
     return attached;
 }
-async function getBrowser(env) {
+/** Resolve the configured provider browser without selecting, claiming, or creating a tab. */
+export async function resolveChatGPTBrowser(env, coordination) {
+    return await getBrowser(env, coordination);
+}
+async function getBrowser(env, coordination) {
     if (env.browser !== undefined) {
-        return env.browser;
+        return createCoordinatedBrowser(env.browser, coordination);
     }
     const anyEnv = env;
     const agent = env.agent ?? anyEnv.agent ?? globalThis.agent;
@@ -36,7 +42,7 @@ async function getBrowser(env) {
             ?? await tryBrowserGet(browsers, "extension")
             ?? await tryBrowserGet(browsers, "chrome");
         if (maybeBrowser !== undefined) {
-            return maybeBrowser;
+            return createCoordinatedBrowser(maybeBrowser, coordination);
         }
     }
     throw new BrowserBridgeUnavailableError();
@@ -95,12 +101,15 @@ async function tryBrowserGetPreferredListed(browsers) {
         return undefined;
     }
 }
-async function getOrCreateChatGPTPage(browser, env, args) {
+async function getOrCreateChatGPTPage(browser, env, args, coordination) {
     const targetUrl = args.url ?? CHATGPT_HOME;
     assertSafeChatGPTNavigation(targetUrl);
     const explicitExistingPolicy = normalizeExplicitExistingTabPolicy(args);
     if (env.page !== undefined) {
-        const cached = normalizePage(env.page);
+        // An invocation can begin with a page captured before browser discovery.
+        // Rebind it to the discovered browser-wide actor, unwrapping only through
+        // the explicit seam so a page is never nested under two coordinators.
+        const cached = createCoordinatedPageForBrowser(normalizePage(env.page), browser, coordination);
         if (await cachedPageMatchesBootstrapArgs(cached, args, explicitExistingPolicy)) {
             return cached;
         }
@@ -553,7 +562,69 @@ function normalizeBrowser(browser) {
     if (browser === undefined || browser === null || typeof browser !== "object") {
         return undefined;
     }
-    return browser;
+    // Browsers returned by the Codex bridge are capability proxies. Reading a
+    // method normally returns a receiver-safe callable, while extracting the
+    // same function from its prototype loses the proxy's private-field binding.
+    // Normalize that trusted bridge result into a plain BrowserLike before the
+    // descriptor-only coordination facade inspects it.
+    const rawBrowser = browser;
+    const normalized = {};
+    const name = providerValue(rawBrowser, "name");
+    if (typeof name === "string")
+        normalized.name = name;
+    const rawUser = providerValue(rawBrowser, "user");
+    if (isProviderRecord(rawUser)) {
+        const openTabs = providerCallable(rawUser, "openTabs");
+        const claimTab = providerCallable(rawUser, "claimTab");
+        normalized.user = {
+            ...(openTabs === undefined ? {} : {
+                openTabs: async () => await openTabs()
+            }),
+            ...(claimTab === undefined ? {} : {
+                claimTab: async (tab) => normalizePage(await claimTab(tab))
+            })
+        };
+    }
+    const rawTabs = providerValue(rawBrowser, "tabs");
+    if (isProviderRecord(rawTabs)) {
+        const create = providerCallable(rawTabs, "create");
+        const newer = providerCallable(rawTabs, "new");
+        const selected = providerCallable(rawTabs, "selected");
+        const list = providerCallable(rawTabs, "list");
+        const get = providerCallable(rawTabs, "get");
+        const finalize = providerCallable(rawTabs, "finalize");
+        normalized.tabs = {
+            ...(create === undefined ? {} : {
+                create: async (url) => normalizePage(await create(url))
+            }),
+            ...(newer === undefined ? {} : {
+                new: async (url) => normalizePage(await newer(...(url === undefined ? [] : [url])))
+            }),
+            ...(selected === undefined ? {} : {
+                selected: async () => {
+                    const page = await selected();
+                    return page === undefined ? undefined : normalizePage(page);
+                }
+            }),
+            ...(list === undefined ? {} : {
+                list: async () => {
+                    const pages = await list();
+                    return Array.isArray(pages) ? pages.map(normalizePage) : pages;
+                }
+            }),
+            ...(get === undefined ? {} : {
+                get: async (id) => normalizePage(await get(id))
+            }),
+            ...(finalize === undefined ? {} : {
+                finalize: async (options) => { await finalize(options); }
+            })
+        };
+    }
+    const newPage = providerCallable(rawBrowser, "newPage");
+    if (newPage !== undefined) {
+        normalized.newPage = async () => normalizePage(await newPage());
+    }
+    return normalized;
 }
 async function hydrateTab(browser, pageOrTab) {
     const maybe = pageOrTab;
@@ -568,28 +639,65 @@ async function hydrateTab(browser, pageOrTab) {
     return normalizePage(pageOrTab);
 }
 function normalizePage(pageOrTab) {
+    if (isPageWrapper(pageOrTab))
+        return pageOrTab;
+    if (!isProviderRecord(pageOrTab))
+        return pageOrTab;
     const maybe = pageOrTab;
-    const playwright = maybe.playwright ?? maybe.page;
-    if (playwright !== undefined && typeof playwright === "object") {
-        return new Proxy(playwright, {
-            get(target, prop) {
-                if (prop in target) {
-                    const value = target[prop];
-                    return typeof value === "function" ? value.bind(target) : value;
-                }
-                const value = maybe[prop];
-                return typeof value === "function" ? value.bind(maybe) : value;
-            }
-        });
+    const embedded = providerValue(maybe, "playwright") ?? providerValue(maybe, "page");
+    const primary = isProviderRecord(embedded) ? embedded : maybe;
+    const normalized = {};
+    for (const property of ["id", "tabId"]) {
+        const value = providerValue(maybe, property) ?? providerValue(primary, property);
+        if (typeof value === "string")
+            normalized[property] = value;
+    }
+    for (const property of ["keyboard", "mouse", "cua", "capabilities"]) {
+        const value = providerValue(primary, property) ?? providerValue(maybe, property);
+        if (isProviderRecord(value))
+            normalized[property] = value;
+    }
+    if (isProviderRecord(embedded))
+        normalized.playwright = embedded;
+    for (const method of [
+        "url", "goto", "title", "locator", "getByRole", "getByPlaceholder",
+        "getByText", "waitForTimeout", "waitForEvent", "evaluate", "content", "close"
+    ]) {
+        const callable = providerCallable(primary, method) ?? providerCallable(maybe, method);
+        if (callable !== undefined)
+            normalized[method] = (...args) => callable(...args);
+    }
+    const stringUrl = providerValue(maybe, "url");
+    if (normalized.url === undefined && typeof stringUrl === "string") {
+        normalized.url = () => stringUrl;
+    }
+    const stringTitle = providerValue(maybe, "title");
+    if (normalized.title === undefined && typeof stringTitle === "string") {
+        normalized.title = async () => stringTitle;
+    }
+    return normalized;
+}
+function isProviderRecord(value) {
+    return (typeof value === "object" && value !== null) || typeof value === "function";
+}
+function providerValue(value, key) {
+    try {
+        return Reflect.get(value, key, value);
     }
-    if (typeof maybe.url === "string") {
-        return {
-            ...maybe,
-            url: () => maybe.url,
-            title: async () => typeof maybe.title === "string" ? maybe.title : ""
-        };
+    catch {
+        return undefined;
     }
-    return pageOrTab;
+}
+function providerCallable(value, key) {
+    const candidate = providerValue(value, key);
+    if (typeof candidate !== "function")
+        return undefined;
+    return (...args) => Reflect.apply(candidate, value, args);
+}
+function isPageWrapper(value) {
+    if (value === null || (typeof value !== "object" && typeof value !== "function"))
+        return false;
+    return unwrapCoordinatedPage(value) !== value;
 }
 export function tabIdFromPage(page) {
     const maybe = page;

package/dist/src/browser/chatgpt-url.d.ts

@@ -6,3 +6,5 @@ export declare const CHATGPT_HOME = "https://chatgpt.com/";
  */
 export declare function isChatGPTUrl(value: string | undefined): boolean;
 export declare function requireChatGPTUrl(value: string, label: string): string;
+/** Public context for ChatGPT's signed attachment endpoint, never its token. */
+export declare function chatGPTAttachmentContextUrl(value: string | undefined): string | undefined;

package/dist/src/browser/chatgpt-url.js

@@ -26,3 +26,12 @@ export function requireChatGPTUrl(value, label) {
     }
     return value;
 }
+/** Public context for ChatGPT's signed attachment endpoint, never its token. */
+export function chatGPTAttachmentContextUrl(value) {
+    if (!isChatGPTUrl(value))
+        return undefined;
+    const url = new URL(value);
+    if (url.pathname !== "/backend-api/estuary/content")
+        return undefined;
+    return `${url.origin}${url.pathname}`;
+}

package/dist/src/browser/downloads.d.ts

@@ -1,7 +1,23 @@
 import type { DownloadedFile, PageLike } from "../types.js";
+import { ChatGPTControlError } from "../errors.js";
 export type DownloadLike = {
     suggestedFilename?: () => string;
+    /** Capability-based stream exposed by Playwright's Download implementation. */
+    createReadStream?: () => Promise<AsyncIterable<Uint8Array>>;
     saveAs?: (path: string) => Promise<void>;
-    path?: () => Promise<string | null>;
+    path?: (options?: {
+        timeoutMs?: number;
+    }) => Promise<string | null>;
 };
+export declare class DownloadReceiptTimeoutError extends ChatGPTControlError {
+    constructor(stage: string);
+}
+export declare class DownloadBrowserBlockedError extends ChatGPTControlError {
+    constructor();
+}
+export declare class DownloadReceiptFailedError extends ChatGPTControlError {
+    constructor();
+}
+export declare function isTerminalDownloadError(error: unknown): error is DownloadReceiptTimeoutError | DownloadBrowserBlockedError | DownloadReceiptFailedError;
+export declare function isTerminalDownloadCode(code: string | undefined): boolean;
 export declare function waitForDownloadFromClick(page: PageLike, click: () => Promise<void>, destDir: string, timeoutMs: number, filenameHint?: string): Promise<DownloadedFile>;