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

package/dist/src/browser/downloads.js

@@ -1,39 +1,161 @@
 import { copyFile, mkdir, stat } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { localGuardTimeout, withTimeout } from "../commands/timeouts.js";
+import { ChatGPTControlError } from "../errors.js";
+import { createDeadline, remainingMs } from "../commands/deadline.js";
+import { withTimeout } from "../commands/timeouts.js";
+import { coordinatedEventRegistrationBarrier, withCoordinatedMutationGuard } from "../runtime/coordinated-page.js";
+export class DownloadReceiptTimeoutError extends ChatGPTControlError {
+    constructor(stage) {
+        super(`Download ${stage} did not complete before the deadline. Completion is unverified; inspect the existing download before retrying.`, "download_unavailable", false, undefined, { code: "download_receipt_timeout", resumable: false });
+    }
+}
+export class DownloadBrowserBlockedError extends ChatGPTControlError {
+    constructor() {
+        super("Chrome displayed ERR_BLOCKED_BY_CLIENT during the download. Inspect the existing download and Chrome restrictions before retrying; completion is unverified.", "download_unavailable", false, undefined, { code: "download_blocked_by_browser", resumable: false });
+    }
+}
+export class DownloadReceiptFailedError extends ChatGPTControlError {
+    constructor() {
+        super("The browser did not provide a verified download receipt. Inspect the existing download before retrying; completion is unverified.", "download_unavailable", false, undefined, { code: "download_receipt_failed", resumable: false });
+    }
+}
+export function isTerminalDownloadError(error) {
+    return error instanceof DownloadReceiptTimeoutError || error instanceof DownloadBrowserBlockedError || error instanceof DownloadReceiptFailedError;
+}
+export function isTerminalDownloadCode(code) {
+    return code === "download_receipt_timeout" || code === "download_blocked_by_browser" || code === "download_receipt_failed";
+}
+async function checkBrowserDownloadError(page, deadline) {
+    if (typeof page.evaluate !== "function")
+        return;
+    // A missing or stalled diagnostic must leave time for the native receipt.
+    // Both probes are read-only, bounded by the existing operation deadline,
+    // and return an enum instead of exporting error-page URLs or body text.
+    const timeoutMs = Math.min(1000, Math.floor(remainingMs(deadline) / 4));
+    if (timeoutMs <= 0)
+        return;
+    let state;
+    try {
+        state = await withTimeout(page.evaluate(function inspectBrowserDownloadError() {
+            if (!document.body?.getAttribute("class")?.split(/\s+/).includes("neterror"))
+                return "unavailable";
+            const frames = document.querySelectorAll("#main-frame-error");
+            if (frames.length !== 1)
+                return "unavailable";
+            const codes = frames[0].querySelectorAll(".error-code");
+            return codes.length === 1 && codes[0].textContent?.trim() === "ERR_BLOCKED_BY_CLIENT"
+                ? "blocked_by_client" : "unavailable";
+        }, undefined, { timeoutMs }), timeoutMs, "Browser download diagnostic timed out.");
+    }
+    catch {
+        return;
+    }
+    if (state === "blocked_by_client")
+        throw new DownloadBrowserBlockedError();
+}
+async function downloadStep(deadline, stage, run, capMs) {
+    const timeoutMs = Math.min(remainingMs(deadline), capMs ?? Number.MAX_SAFE_INTEGER);
+    const timeoutError = new DownloadReceiptTimeoutError(stage);
+    if (timeoutMs <= 0)
+        throw timeoutError;
+    try {
+        return await withTimeout(run(), timeoutMs, timeoutError.message);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === timeoutError.message)
+            throw timeoutError;
+        throw error;
+    }
+}
 export async function waitForDownloadFromClick(page, click, destDir, timeoutMs, filenameHint) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new Error("Download timeout must be positive and within the supported timer range.");
+    }
+    const deadline = createDeadline(timeoutMs);
+    await checkBrowserDownloadError(page, deadline);
     const absoluteDest = resolve(destDir);
-    await mkdir(absoluteDest, { recursive: true });
-    const downloadPromise = page.waitForEvent?.("download", { timeout: timeoutMs, timeoutMs });
-    if (downloadPromise === undefined) {
+    await downloadStep(deadline, "destination preparation", () => mkdir(absoluteDest, { recursive: true }));
+    if (typeof page.waitForEvent !== "function") {
         throw new Error("The active browser page does not expose download events.");
     }
-    await withTimeout(click(), localGuardTimeout(timeoutMs, 10000), "Download control click did not complete before the local guard timeout.");
-    const download = await downloadPromise;
-    const sourcePath = typeof download.path === "function" ? await download.path() : null;
-    const suggestedFilename = filenameHint
-        ?? download.suggestedFilename?.()
-        ?? (sourcePath === null ? undefined : basename(sourcePath))
-        ?? `chatgpt-download-${Date.now()}`;
-    const targetPath = join(absoluteDest, basename(suggestedFilename));
-    if (typeof download.saveAs === "function") {
-        await download.saveAs(targetPath);
-    }
-    else if (sourcePath !== null) {
-        if (resolve(sourcePath) !== resolve(targetPath)) {
-            await copyFile(sourcePath, targetPath);
+    // Arm before activation. Promise.all observes both rejections immediately,
+    // including a late event rejection after a failed or timed-out click.
+    const nativeTimeoutMs = remainingMs(deadline);
+    if (nativeTimeoutMs <= 0)
+        throw new DownloadReceiptTimeoutError("event registration");
+    const activation = new AbortController();
+    let failure;
+    const assertActive = () => {
+        if (failure !== undefined)
+            throw failure;
+        if (activation.signal.aborted || remainingMs(deadline) <= 0)
+            throw new DownloadReceiptTimeoutError("control click");
+    };
+    try {
+        const rawWait = page.waitForEvent("download", { timeout: nativeTimeoutMs, timeoutMs: nativeTimeoutMs });
+        const registration = coordinatedEventRegistrationBarrier(rawWait);
+        let receiptFailed = false;
+        const downloadPromise = downloadStep(deadline, "event receipt", () => rawWait).catch(error => {
+            receiptFailed = true;
+            failure = isTerminalDownloadError(error) ? error : new DownloadReceiptFailedError();
+            activation.abort(failure);
+            throw failure;
+        });
+        const [download] = await Promise.all([
+            downloadPromise,
+            (async () => {
+                // Actor fairness may choose a queued mutation before another read.
+                // Registration must finish before the activating click is even queued.
+                if (registration !== undefined)
+                    await downloadStep(deadline, "event registration", () => registration);
+                try {
+                    await downloadStep(deadline, "control click", () => withCoordinatedMutationGuard(activation.signal, assertActive, click), 10_000);
+                }
+                catch (error) {
+                    if (!receiptFailed)
+                        await checkBrowserDownloadError(page, deadline);
+                    throw error;
+                }
+                if (!receiptFailed)
+                    await checkBrowserDownloadError(page, deadline);
+            })()
+        ]);
+        // saveAs is already a complete capability; an optional path() call can hang
+        // on bridge implementations and is unnecessary when saveAs is available.
+        const sourcePath = typeof download.saveAs !== "function" && typeof download.path === "function"
+            ? await downloadStep(deadline, "source path", () => download.path({ timeoutMs: remainingMs(deadline) })) : null;
+        const suggestedFilename = filenameHint
+            ?? download.suggestedFilename?.()
+            ?? (sourcePath === null ? undefined : basename(sourcePath))
+            ?? `chatgpt-download-${Date.now()}`;
+        const targetPath = join(absoluteDest, basename(suggestedFilename));
+        if (typeof download.saveAs === "function") {
+            await downloadStep(deadline, "file save", () => download.saveAs(targetPath));
+        }
+        else if (sourcePath !== null) {
+            if (resolve(sourcePath) !== resolve(targetPath)) {
+                await downloadStep(deadline, "file copy", () => copyFile(sourcePath, targetPath));
+            }
+        }
+        else {
+            throw new Error("The browser download object exposes neither saveAs() nor a completed local path().");
         }
+        const saved = await downloadStep(deadline, "file verification", () => stat(targetPath));
+        if (saved.size <= 0) {
+            throw new Error(`Downloaded file is empty: ${targetPath}`);
+        }
+        return {
+            path: targetPath,
+            suggestedFilename,
+            bytes: saved.size
+        };
     }
-    else {
-        throw new Error("The browser download object exposes neither saveAs() nor a completed local path().");
+    catch (error) {
+        throw failure ?? (isTerminalDownloadError(error) ? error : new DownloadReceiptFailedError());
     }
-    const saved = await stat(targetPath);
-    if (saved.size <= 0) {
-        throw new Error(`Downloaded file is empty: ${targetPath}`);
+    finally {
+        // Cancels locally queued activation only. A native download already in
+        // progress, or its native event listener, is not claimed to be cancelled.
+        activation.abort();
     }
-    return {
-        path: targetPath,
-        suggestedFilename,
-        bytes: saved.size
-    };
 }

package/dist/src/browser/page-state.js

@@ -2,6 +2,7 @@ import { classifyVisibleText } from "../safety/blockers.js";
 import { compactVisibleText } from "../safety/redaction.js";
 import { escapeRegExp, localeLabels } from "../dom/locale-labels.js";
 import { withTimeout } from "../commands/timeouts.js";
+import { chatGPTAttachmentContextUrl } from "./chatgpt-url.js";
 export function parseConversationId(url) {
     let parsed;
     try {
@@ -19,6 +20,11 @@ export function parseConversationId(url) {
 export async function readPageState(page) {
     const rawUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";
     const url = typeof rawUrl === "string" ? rawUrl : "";
+    // This is a file transfer endpoint, not a conversation surface. Keep the
+    // internal URL for origin checks without inspecting error-page content.
+    if (chatGPTAttachmentContextUrl(url) !== undefined) {
+        return { url, visibleText: "", signedIn: false };
+    }
     const rawTitle = typeof page.title === "function" ? await page.title().catch(() => undefined) : undefined;
     const title = typeof rawTitle === "string" ? rawTitle : undefined;
     const surface = await readPageSurfaceSnapshot(page);

package/dist/src/client.d.ts

@@ -6,6 +6,12 @@ import type { ChatGPTAgent, ChatGPTAgentConfig, ChatGPTResponse, ChatGPTRunner,
 import { type ChatGPTResponsesCreateArgs } from "./runner/responses.js";
 import { type ReportRedactionOptions } from "./safety/report-redaction.js";
 import { type BlockerExplanation, type ExplainBlockerOptions } from "./diagnostics/blockers.js";
+import { type OperationAdapterFactory, type OperationControlAdapterFactory, type OperationClientCollectOptions, type OperationClientControlOptions, type OperationClientRunOptions, type OperationClientSubmitOptions, type OperationHandleAdapterFactory } from "./operations/client.js";
+import { type OperationBrowserAdapter } from "./operations/service.js";
+import type { OperationControlRequestV1, OperationHandleV1, OperationSubmitRequestV1 } from "./operations/types.js";
+import type { CollectorResult } from "./operations/collector.js";
+import type { ControlResult } from "./operations/control.js";
+import type { OperationInspectResult, OperationRunResult, OperationSubmitResult } from "./operations/service.js";
 export type ChatGPTClientOptions = RuntimeEnv & {
     defaults?: {
         experience?: Exclude<ChatGPTExperience, "unknown">;
@@ -18,7 +24,41 @@ export type ChatGPTClientOptions = RuntimeEnv & {
     };
     limits?: Partial<RunLimits>;
     reporting?: RunReportOptions;
+    /** Additive transactional operation surface. Construction remains synchronous; journal opening is lazy. */
+    operations?: ChatGPTOperationsOptions;
 };
+/**
+ * Configuration for the additive transactional operation surface.
+ *
+ * The default state root is the platform application-state directory owned by
+ * `OperationJournal`. Set `stateRoot` explicitly when multiple cooperating
+ * clients must share a project-local journal. Browser adapters are opt-in:
+ * without one, durable inspection still works but browser-touching calls fail
+ * closed with an adapter blocker.
+ */
+export type ChatGPTOperationsOptions = Readonly<{
+    stateRoot?: string;
+    /** Explicit private-file connection to a normal Node journal authority. */
+    journalService?: Readonly<{
+        descriptorPath: string;
+        timeoutMs?: number;
+    }>;
+    adapter?: OperationBrowserAdapter;
+    adapterFactory?: OperationAdapterFactory;
+    handleAdapterFactory?: OperationHandleAdapterFactory;
+    /** Fresh request-local adapter for Stop or Work steer; never cached. */
+    controlAdapterFactory?: OperationControlAdapterFactory;
+    maxCachedAdapters?: number;
+    maxCasRetries?: number;
+}>;
+/** Stable, lazily initialized facade exposed as `chatgpt.operations`. */
+export type ChatGPTOperations = Readonly<{
+    submit(request: OperationSubmitRequestV1, options?: OperationClientSubmitOptions): Promise<OperationSubmitResult>;
+    collect(handle: OperationHandleV1, options?: OperationClientCollectOptions): Promise<CollectorResult>;
+    inspect(handle: OperationHandleV1): Promise<OperationInspectResult>;
+    control(request: OperationControlRequestV1, options?: OperationClientControlOptions): Promise<ControlResult>;
+    run(request: OperationSubmitRequestV1, options?: OperationClientRunOptions): Promise<OperationRunResult>;
+}>;
 export type RunLimits = {
     maxPromptsPerRun: number;
     maxThreadsOpenedPerRun: number;
@@ -58,6 +98,8 @@ export type FileInput = string | {
 };
 export type AskWorkflowArgs = {
     prompt: string;
+    /** Caller-owned durable identity. Supplying it opts this invocation into the transactional operation path. */
+    operationId?: string;
     thread?: WorkflowThread;
     existingTab?: BootstrapArgs["existingTab"];
     preferExistingTab?: boolean;
@@ -107,6 +149,7 @@ export type ChatGPTClient = {
     agent<TOutput = string>(config: ChatGPTAgentConfig<TOutput>): ChatGPTAgent<TOutput>;
     run<TOutput = string>(agent: ChatGPTAgent<TOutput>, input: ChatGPTRunInput): Promise<ChatGPTRunResult<TOutput>>;
     runner: ChatGPTRunner;
+    operations: ChatGPTOperations;
     responses: {
         create(args: ChatGPTResponsesCreateArgs | Record<string, unknown>): Promise<ChatGPTResponse>;
     };