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

package/dist/src/backend/protocol.d.ts

@@ -1,7 +1,7 @@
 export declare const BACKEND_REQUEST_SCHEMA_VERSION: "chatgpt.browser_control.backend_request.v1";
 export declare const BACKEND_RESPONSE_SCHEMA_VERSION: "chatgpt.browser_control.backend_response.v1";
 export declare const BACKEND_EVENT_SCHEMA_VERSION: "chatgpt.browser_control.backend_event.v1";
-export declare const backendCommands: readonly ["backend.version", "backend.health", "backend.capabilities", "runner.run", "runner.plan", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "runMessages", "openThread", "readLatest", "copyLatest", "downloadLatest", "runPlan", "doctor", "createReport", "reports.create", "reports.redact", "reports.summarize", "commands", "describe", "help", "session.bootstrap", "threads.new", "threads.search", "threads.open", "messages.compose", "messages.submit", "messages.ask", "messages.wait", "messages.readLatest", "messages.waitAndRead", "artifacts.listLatest", "artifacts.wait", "artifacts.downloadLatest", "files.preflight", "files.attach", "files.downloadLatest", "projects.sources.list", "projects.sources.planAdd", "projects.sources.add", "modes.set", "tools.select", "response.copy"];
+export declare const backendCommands: readonly ["backend.version", "backend.health", "backend.capabilities", "runner.run", "runner.plan", "runner.stream", "responses.create", "ask", "askInThread", "askWithFiles", "askAndDownload", "runMessages", "openThread", "readLatest", "copyLatest", "downloadLatest", "runPlan", "doctor", "createReport", "reports.create", "reports.redact", "reports.summarize", "commands", "describe", "help", "session.bootstrap", "threads.new", "threads.search", "threads.open", "messages.compose", "messages.submit", "messages.ask", "messages.wait", "messages.readLatest", "messages.waitAndRead", "artifacts.listLatest", "artifacts.wait", "artifacts.downloadLatest", "files.preflight", "files.attach", "files.downloadLatest", "projects.sources.list", "projects.sources.planAdd", "projects.sources.add", "modes.set", "modes.get", "tools.select", "response.copy"];
 export type BackendCommand = typeof backendCommands[number];
 export type BackendRequest = {
     schemaVersion: typeof BACKEND_REQUEST_SCHEMA_VERSION;

package/dist/src/backend/protocol.js

@@ -47,6 +47,7 @@ export const backendCommands = [
     "projects.sources.planAdd",
     "projects.sources.add",
     "modes.set",
+    "modes.get",
     "tools.select",
     "response.copy"
 ];

package/dist/src/backend/session.js

@@ -161,6 +161,8 @@ async function dispatchBackendCommand(client, request) {
             return client.projects.sources.add(payload);
         case "modes.set":
             return client.modes.set(payload);
+        case "modes.get":
+            return client.modes.get(emptyToUndefined(payload));
         case "tools.select":
             return client.tools.select(payload);
         case "response.copy":

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

@@ -1,2 +1,13 @@
+export type ClipboardReadCommand = {
+    command: string;
+    args: string[];
+};
+/**
+ * Ordered clipboard-read command candidates for a platform. The first command that
+ * succeeds wins; callers fall back to DOM extraction when none do. Linux ordering
+ * prefers Wayland's wl-paste only when a Wayland session is detectable, otherwise the
+ * X11 tools go first so plain X sessions do not pay a doomed wl-paste attempt.
+ */
+export declare function clipboardReadCommandsForPlatform(platform: NodeJS.Platform, env?: Record<string, string | undefined>): ClipboardReadCommand[];
 export declare function readSystemClipboard(): Promise<string | undefined>;
 export declare function waitForClipboardChange(before: string | undefined, timeoutMs: number, pollMs?: number): Promise<string | undefined>;

package/dist/src/browser/clipboard.js

@@ -1,17 +1,44 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-export async function readSystemClipboard() {
-    if (typeof process === "undefined" || process.platform !== "darwin") {
-        return undefined;
+/**
+ * Ordered clipboard-read command candidates for a platform. The first command that
+ * succeeds wins; callers fall back to DOM extraction when none do. Linux ordering
+ * prefers Wayland's wl-paste only when a Wayland session is detectable, otherwise the
+ * X11 tools go first so plain X sessions do not pay a doomed wl-paste attempt.
+ */
+export function clipboardReadCommandsForPlatform(platform, env = {}) {
+    if (platform === "darwin") {
+        return [{ command: "pbpaste", args: [] }];
+    }
+    if (platform === "win32") {
+        return [{ command: "powershell.exe", args: ["-NoProfile", "-Command", "Get-Clipboard -Raw"] }];
     }
-    try {
-        const { stdout } = await execFileAsync("pbpaste", [], { timeout: 2000, maxBuffer: 10 * 1024 * 1024 });
-        return stdout;
+    if (platform === "linux") {
+        const waylandCommand = { command: "wl-paste", args: ["--no-newline"] };
+        const x11Commands = [
+            { command: "xclip", args: ["-selection", "clipboard", "-o"] },
+            { command: "xsel", args: ["--clipboard", "--output"] }
+        ];
+        const isWayland = typeof env.WAYLAND_DISPLAY === "string" && env.WAYLAND_DISPLAY.length > 0;
+        return isWayland ? [waylandCommand, ...x11Commands] : [...x11Commands, waylandCommand];
     }
-    catch {
+    return [];
+}
+export async function readSystemClipboard() {
+    if (typeof process === "undefined") {
         return undefined;
     }
+    for (const { command, args } of clipboardReadCommandsForPlatform(process.platform, process.env)) {
+        try {
+            const { stdout } = await execFileAsync(command, args, { timeout: 2000, maxBuffer: 10 * 1024 * 1024 });
+            return stdout;
+        }
+        catch {
+            // Missing tool or empty clipboard: try the next candidate.
+        }
+    }
+    return undefined;
 }
 export async function waitForClipboardChange(before, timeoutMs, pollMs = 150) {
     const started = Date.now();

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

@@ -3,8 +3,18 @@ import { compactVisibleText } from "../safety/redaction.js";
 import { escapeRegExp, localeLabels } from "../dom/locale-labels.js";
 import { withTimeout } from "../commands/timeouts.js";
 export function parseConversationId(url) {
-    const match = /\/c\/([A-Za-z0-9-]+)/.exec(url);
-    return match?.[1];
+    let parsed;
+    try {
+        parsed = new URL(url, "https://chatgpt.com");
+    }
+    catch {
+        return undefined;
+    }
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    if (segments[0] !== "c" || segments[1] === undefined || segments[1].length === 0) {
+        return undefined;
+    }
+    return segments[1];
 }
 export async function readPageState(page) {
     const rawUrl = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => "") : "";

package/dist/src/client.d.ts

@@ -1,4 +1,4 @@
-import type { AskArgs, ArtifactDownloadArgs, ArtifactWaitArgs, AttachFilesArgs, BootstrapArgs, CommandResult, CopyResponseArgs, DownloadLatestArgs, FilePreflightArgs, FilePreflightData, ListArtifactsArgs, NewThreadArgs, OpenThreadArgs, ProjectSourcesAddArgs, ProjectSourcesAddData, ProjectSourcesAddPlanData, ProjectSourcesListArgs, ProjectSourcesListData, ProjectSourcesPlanAddArgs, ReadLatestArgs, RuntimeEnv, SearchThreadsArgs, SelectToolArgs, SequencePlan, SetModeArgs, ThreadTarget, WaitArgs } from "./types.js";
+import type { AskArgs, ArtifactDownloadArgs, ArtifactWaitArgs, AttachFilesArgs, BootstrapArgs, CommandResult, CopyResponseArgs, DownloadLatestArgs, FilePreflightArgs, FilePreflightData, GetModeArgs, GetModeData, ListArtifactsArgs, NewThreadArgs, OpenThreadArgs, ProjectSourcesAddArgs, ProjectSourcesAddData, ProjectSourcesAddPlanData, ProjectSourcesListArgs, ProjectSourcesListData, ProjectSourcesPlanAddArgs, ReadLatestArgs, RuntimeEnv, SearchThreadsArgs, SelectToolArgs, SequencePlan, SetModeArgs, ThreadTarget, WaitArgs } from "./types.js";
 import { type DoctorArgs, type DoctorReport } from "./commands/doctor.js";
 import { type RunReportData, type RunReportOptions } from "./commands/reports.js";
 import { type CommandDescriptor } from "./commands/registry.js";
@@ -171,6 +171,7 @@ export type ChatGPTClient = {
     };
     modes: {
         set(args: SetModeArgs): Promise<CommandResult<unknown>>;
+        get(args?: GetModeArgs): Promise<CommandResult<GetModeData>>;
     };
     tools: {
         select(args: SelectToolArgs): Promise<CommandResult<unknown>>;

package/dist/src/client.js

@@ -3,7 +3,7 @@ import { attachFiles, downloadLatestFile, preflightFiles } from "./commands/file
 import { addProjectSources, buildProjectSourceAddPlan, listProjectSources } from "./commands/project-sources.js";
 import { doctor } from "./commands/doctor.js";
 import { askMessage, composeMessage, readLatest, submitMessage, waitAndRead, waitForMessage } from "./commands/messages.js";
-import { selectTool, setMode } from "./commands/modes.js";
+import { getMode, selectTool, setMode } from "./commands/modes.js";
 import { createRunReport } from "./commands/reports.js";
 import { copyResponse } from "./commands/response-actions.js";
 import { commandDescriptors, describeCommand, helpText } from "./commands/registry.js";
@@ -91,7 +91,8 @@ export function createChatGPT(options = {}) {
             downloadLatest: args => downloadLatestArtifact(env, args)
         },
         modes: {
-            set: args => setMode(env, args)
+            set: args => setMode(env, args),
+            get: args => getMode(env, args)
         },
         tools: {
             select: args => selectTool(env, args)

package/dist/src/commands/context.js

@@ -6,7 +6,9 @@ export async function contextFromPage(page, partial = {}) {
         return { timestamp: new Date().toISOString(), ...partial };
     }
     const url = typeof page.url === "function" ? await Promise.resolve(page.url()).catch(() => partial.url) : partial.url;
-    const title = typeof page.title === "function" ? await page.title().catch(() => undefined) : partial.title;
+    const title = typeof page.title === "function"
+        ? await withTimeout(page.title(), 1000, "Timed out while reading page title.").catch(() => partial.title)
+        : partial.title;
     const [turnCount, assistantTurnCount] = await Promise.all([
         withTimeout(countPageMessages(page), 1000, "Timed out while counting page messages.").catch(() => partial.turnCount),
         withTimeout(countPageMessages(page, "assistant"), 1000, "Timed out while counting assistant messages.").catch(() => partial.assistantTurnCount)

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

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

package/dist/src/commands/conversation.js

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

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

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

package/dist/src/commands/deadline.js

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

package/dist/src/commands/doctor.js

@@ -31,6 +31,7 @@ const REQUIRED_LOCALE_KEYS = [
     "rateLimitBlocker"
 ];
 const REQUIRED_TOOL_IDS = ["web_search", "deep_research", "create_image"];
+const REQUIRED_MODE_OPTION_IDS = ["latest", "instant", "thinking", "extended", "medium", "high", "extraHigh", "pro"];
 export async function doctor(env, args = {}) {
     const wanted = args.check ?? DEFAULT_CHECKS;
     const checks = {};
@@ -229,23 +230,29 @@ async function filePreflightCheck(env, args) {
 function localizationCheck(env) {
     const requiredKeysMissing = REQUIRED_LOCALE_KEYS.filter(key => localeLabels[key].length === 0);
     const missingToolIds = REQUIRED_TOOL_IDS.filter(id => (localeLabels.tools[id]?.length ?? 0) === 0);
+    const missingModeOptionIds = REQUIRED_MODE_OPTION_IDS.filter(id => (localeLabels.modeOptions[id]?.length ?? 0) === 0);
     const toolIds = Object.keys(localeLabels.tools);
+    const modeOptionIds = Object.keys(localeLabels.modeOptions);
     const englishCanonicalPresent = localeLabels.composerTextbox[0] === "Chat with ChatGPT"
         && localeLabels.sendButton[0] === "Send prompt"
         && localeLabels.modeLabels.includes("Thinking")
+        && localeLabels.modeOptions.pro?.[0] === "Pro"
         && localeLabels.tools.web_search?.[0] === "Web search";
     const labelCandidateCount = REQUIRED_LOCALE_KEYS.reduce((total, key) => total + localeLabels[key].length, 0)
-        + Object.values(localeLabels.tools).reduce((total, values) => total + values.length, 0);
+        + Object.values(localeLabels.tools).reduce((total, values) => total + values.length, 0)
+        + Object.values(localeLabels.modeOptions).reduce((total, values) => total + values.length, 0);
     const details = {
         englishCanonicalPresent,
         requiredKeysMissing,
         missingToolIds,
+        missingModeOptionIds,
         toolIds,
+        modeOptionIds,
         labelCandidateCount,
         pageAvailable: env.page !== undefined,
         runtimeSelectorCoverage: "registry_only_stage_2"
     };
-    if (englishCanonicalPresent && requiredKeysMissing.length === 0 && missingToolIds.length === 0) {
+    if (englishCanonicalPresent && requiredKeysMissing.length === 0 && missingToolIds.length === 0 && missingModeOptionIds.length === 0) {
         return unknown("The locale registry is loaded; localized runtime selector coverage is registry-only in Stage 2 and not fully proven.", undefined, details);
     }
     return blocked("The locale registry is missing canonical labels required for selector fallback.", ["Update src/dom/locale-labels.ts or src/dom/locale/* with verified visible labels before relying on localized controls."], details, "selector_drift");

package/dist/src/commands/files.js

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