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

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

@@ -6,7 +6,7 @@ import type { ChatGPTResponsesCreateArgs } from "../runner/responses.js";
 import type { ChatGPTRunStream } from "../runner/stream.js";
 import type { ChatGPTAgent, ChatGPTAgentConfig, ChatGPTResponse, ChatGPTRunInput, ChatGPTRunResult } from "../runner/types.js";
 import type { ReportRedactionOptions } from "../safety/report-redaction.js";
-import type { BootstrapArgs, CommandResult, CopyResponseArgs, DownloadLatestArgs, NewThreadArgs, OpenThreadArgs, ReadLatestArgs, SearchThreadsArgs, SelectToolArgs, SequencePlan, SetModeArgs, WaitArgs } from "../types.js";
+import type { ArtifactDownloadArgs, ArtifactWaitArgs, BootstrapArgs, CommandResult, CopyResponseArgs, DownloadLatestArgs, ListArtifactsArgs, NewThreadArgs, OpenThreadArgs, ReadLatestArgs, SearchThreadsArgs, SelectToolArgs, SequencePlan, SetModeArgs, WaitArgs } from "../types.js";
 import { type BackendEvent, type BackendRequest, type BackendResponse } from "./protocol.js";
 export type BackendTransport = {
     request(request: BackendRequest): Promise<BackendResponse>;
@@ -44,6 +44,11 @@ export type ChatGPTBackendClient = {
     readLatest(args?: ReadLatestArgs): Promise<CommandResult<unknown>>;
     copyLatest(args?: CopyResponseArgs): Promise<CommandResult<unknown>>;
     downloadLatest(args: DownloadLatestArgs): Promise<CommandResult<unknown>>;
+    artifacts: {
+        listLatest(args?: ListArtifactsArgs): Promise<CommandResult<unknown>>;
+        wait(args?: ArtifactWaitArgs): Promise<CommandResult<unknown>>;
+        downloadLatest(args: ArtifactDownloadArgs): Promise<CommandResult<unknown>>;
+    };
     runPlan(plan: SequencePlan | NamedWorkflowInvocation): Promise<CommandResult<unknown>>;
     doctor(args?: DoctorArgs): Promise<CommandResult<DoctorReport>>;
     createReport(result: CommandResult<unknown>, args?: RunReportOptions): Promise<CommandResult<RunReportData>>;

package/dist/src/backend/client.js

@@ -76,6 +76,11 @@ export function createChatGPTBackendClient(transport) {
             readLatest: args => request("messages.readLatest", args ?? {}),
             waitAndRead: args => request("messages.waitAndRead", args)
         },
+        artifacts: {
+            listLatest: args => request("artifacts.listLatest", args ?? {}),
+            wait: args => request("artifacts.wait", args ?? {}),
+            downloadLatest: args => request("artifacts.downloadLatest", args)
+        },
         files: {
             attach: args => request("files.attach", args),
             downloadLatest: args => request("files.downloadLatest", args)

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", "files.attach", "files.downloadLatest", "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

@@ -37,9 +37,17 @@ export const backendCommands = [
     "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"
 ];

package/dist/src/backend/session.js

@@ -141,12 +141,28 @@ async function dispatchBackendCommand(client, request) {
             return client.messages.readLatest(emptyToUndefined(payload));
         case "messages.waitAndRead":
             return client.messages.waitAndRead(payload);
+        case "artifacts.listLatest":
+            return client.artifacts.listLatest(emptyToUndefined(payload));
+        case "artifacts.wait":
+            return client.artifacts.wait(emptyToUndefined(payload));
+        case "artifacts.downloadLatest":
+            return client.artifacts.downloadLatest(payload);
+        case "files.preflight":
+            return client.files.preflight(payload);
         case "files.attach":
             return client.files.attach(payload);
         case "files.downloadLatest":
             return client.files.downloadLatest(payload);
+        case "projects.sources.list":
+            return client.projects.sources.list(payload);
+        case "projects.sources.planAdd":
+            return client.projects.sources.planAdd(payload);
+        case "projects.sources.add":
+            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/attach.js

@@ -2,6 +2,8 @@ import { BrowserBridgeUnavailableError, ChatGPTControlError, LoginRequiredError
 import { parseConversationId, readPageState } from "./page-state.js";
 const CHATGPT_HOME = "https://chatgpt.com/";
 const CHATGPT_HOSTS = new Set(["chatgpt.com", "www.chatgpt.com", "chat.openai.com"]);
+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);
@@ -102,12 +104,12 @@ async function getOrCreateChatGPTPage(browser, env, args) {
     }
     if (explicitExistingPolicy !== undefined) {
         const existing = await selectExistingTab(browser, explicitExistingPolicy);
-        if (existing !== undefined) {
-            return existing;
+        if (existing.page !== undefined) {
+            return existing.page;
         }
         const ifMissing = explicitExistingPolicy.ifMissing ?? "block";
         if (ifMissing === "block") {
-            throw new ExistingTabSelectionError("No already-open ChatGPT tab matched the requested existing-tab target.", "existing_tab_not_found");
+            throw new ExistingTabSelectionError("No already-open ChatGPT tab matched the requested existing-tab target.", "existing_tab_not_found", existing.diagnostics?.candidateTabs, existing.diagnostics);
         }
         const missingUrl = ifMissing === "open"
             ? urlFromExistingTarget(explicitExistingPolicy.target) ?? targetUrl
@@ -163,8 +165,8 @@ function normalizeExplicitExistingTabPolicy(args) {
     };
 }
 async function selectExistingTab(browser, policy) {
-    const userMatch = await selectExistingUserTab(browser, policy);
-    if (userMatch !== undefined) {
+    const userMatch = await selectExistingUserTab(browser, policy, shouldCollectExistingTabDiagnostics(policy));
+    if (userMatch.page !== undefined) {
         return userMatch;
     }
     if (policy.target?.type === "selected" && typeof browser.tabs?.selected === "function") {
@@ -172,7 +174,7 @@ async function selectExistingTab(browser, policy) {
         if (selected !== undefined) {
             const normalized = normalizePage(selected);
             if (await pageMatchesExistingTarget(normalized, policy)) {
-                return normalized;
+                return { page: normalized };
             }
         }
     }
@@ -181,28 +183,37 @@ async function selectExistingTab(browser, policy) {
         if (tab !== undefined) {
             const normalized = normalizePage(tab);
             if (await pageMatchesExistingTarget(normalized, policy)) {
-                return normalized;
+                return { page: normalized };
             }
         }
     }
-    return undefined;
+    return userMatch.diagnostics === undefined
+        ? { diagnostics: diagnosticsForUnavailableUserTabs(policy) }
+        : userMatch;
 }
-async function selectExistingUserTab(browser, policy) {
+async function selectExistingUserTab(browser, policy, collectDiagnostics) {
     const openTabs = browser.user?.openTabs;
     const claimTab = browser.user?.claimTab;
     if (typeof openTabs !== "function" || typeof claimTab !== "function") {
-        return undefined;
+        return {};
+    }
+    const tabs = await Promise.resolve(openTabs.call(browser.user)).catch(() => undefined);
+    if (tabs === undefined) {
+        return collectDiagnostics
+            ? { diagnostics: diagnosticsForUnavailableUserTabs(policy, "user_open_tabs_unavailable") }
+            : {};
     }
-    const tabs = await Promise.resolve(openTabs.call(browser.user)).catch(() => []);
     const matches = tabs.filter(tab => userTabMatchesTarget(tab, policy));
+    const diagnostics = collectDiagnostics ? diagnosticsForUserTabs(policy, tabs, matches) : undefined;
     if (matches.length === 0) {
-        return undefined;
+        return diagnostics === undefined ? {} : { diagnostics };
     }
     if (matches.length > 1 && (policy.ifMultiple ?? "block") !== "first") {
-        throw new ExistingTabSelectionError("Multiple already-open ChatGPT tabs matched the requested existing-tab target.", "existing_tab_ambiguous", matches);
+        throw new ExistingTabSelectionError("Multiple already-open ChatGPT tabs matched the requested existing-tab target.", "existing_tab_ambiguous", matches, diagnostics);
     }
     const selected = matches[0];
-    return normalizePage(await claimTab.call(browser.user, selected));
+    const page = normalizePage(await claimTab.call(browser.user, selected));
+    return diagnostics === undefined ? { page } : { page, diagnostics };
 }
 function userTabMatchesTarget(tab, policy) {
     const target = policy.target ?? { type: "selected", host: "chatgpt" };
@@ -224,6 +235,100 @@ function userTabMatchesTarget(tab, policy) {
             return titleMatches(tab.title, target.title, target.exact ?? true);
     }
 }
+function diagnosticsForUserTabs(policy, tabs, matches) {
+    const chatgptTabs = tabs.filter(tab => isChatGPTUrl(tab.url));
+    const candidateTabs = matches.length > 1 ? matches : chatgptTabs;
+    const cappedTabs = candidateTabs.slice(0, MAX_EXISTING_TAB_DIAGNOSTIC_CANDIDATES);
+    const diagnostics = {
+        requestedTarget: diagnosticTarget(policy.target ?? { type: "selected", host: "chatgpt" }),
+        userOpenTabsAvailable: true,
+        chatgptTabCount: chatgptTabs.length,
+        mismatchReason: matches.length > 1 ? "multiple_candidates" : mismatchReasonForNoMatches(policy, tabs, chatgptTabs),
+        candidateTabs: cappedTabs.map(diagnosticCandidate)
+    };
+    const omittedCandidateCount = candidateTabs.length - cappedTabs.length;
+    if (omittedCandidateCount > 0)
+        diagnostics.omittedCandidateCount = omittedCandidateCount;
+    return diagnostics;
+}
+function shouldCollectExistingTabDiagnostics(policy) {
+    return (policy.ifMissing ?? "block") === "block" || (policy.ifMultiple ?? "block") !== "first";
+}
+function diagnosticsForUnavailableUserTabs(policy, mismatchReason = undefined) {
+    const target = policy.target ?? { type: "selected", host: "chatgpt" };
+    return {
+        requestedTarget: diagnosticTarget(target),
+        userOpenTabsAvailable: false,
+        chatgptTabCount: 0,
+        mismatchReason: mismatchReason ?? (target.type === "tabId" ? "explicit_tab_id_not_open" : "selected_tab_unavailable"),
+        candidateTabs: []
+    };
+}
+function diagnosticTarget(target) {
+    switch (target.type) {
+        case "selected": {
+            const value = { type: target.type };
+            if (target.host !== undefined)
+                value.host = target.host;
+            return value;
+        }
+        case "tabId":
+            return { type: target.type, tabId: target.tabId };
+        case "conversationId":
+        case "conversation_id":
+            return { type: target.type, conversationId: target.conversationId };
+        case "url":
+            return { type: target.type, url: target.url };
+        case "title": {
+            const value = { type: target.type, title: target.title };
+            if (target.exact !== undefined)
+                value.exact = target.exact;
+            return value;
+        }
+    }
+}
+function diagnosticCandidate(tab) {
+    const candidate = { id: tab.id };
+    if (tab.url !== undefined) {
+        candidate.url = truncateDiagnosticField(tab.url);
+        const conversationId = parseConversationId(tab.url);
+        if (conversationId !== undefined)
+            candidate.conversationId = conversationId;
+    }
+    if (tab.title !== undefined)
+        candidate.title = truncateDiagnosticField(tab.title);
+    if (tab.lastOpened !== undefined)
+        candidate.lastOpened = truncateDiagnosticField(tab.lastOpened);
+    if (tab.tabGroup !== undefined)
+        candidate.tabGroup = truncateDiagnosticField(tab.tabGroup);
+    return candidate;
+}
+function truncateDiagnosticField(value) {
+    return value.length <= MAX_EXISTING_TAB_DIAGNOSTIC_FIELD_LENGTH
+        ? value
+        : `${value.slice(0, MAX_EXISTING_TAB_DIAGNOSTIC_FIELD_LENGTH - 1)}…`;
+}
+function mismatchReasonForNoMatches(policy, tabs, chatgptTabs) {
+    const target = policy.target ?? { type: "selected", host: "chatgpt" };
+    if (tabs.length === 0)
+        return "no_candidate";
+    if (chatgptTabs.length === 0 && (policy.requireChatGPT ?? targetRequiresChatGPT(target))) {
+        return "non_chatgpt_tab";
+    }
+    switch (target.type) {
+        case "tabId":
+            return tabs.some(tab => tab.id === target.tabId) ? "non_chatgpt_tab" : "explicit_tab_id_not_open";
+        case "conversationId":
+        case "conversation_id":
+            return "conversation_id_mismatch";
+        case "url":
+            return "url_mismatch";
+        case "title":
+            return "title_mismatch";
+        case "selected":
+            return "selected_tab_unavailable";
+    }
+}
 async function pageMatchesExistingTarget(page, policy) {
     const url = await Promise.resolve(page.url?.()).catch(() => undefined);
     const title = await Promise.resolve(page.title?.()).catch(() => undefined);
@@ -239,9 +344,9 @@ async function findExistingChatGPTTab(browser) {
         target: { type: "selected", host: "chatgpt" },
         ifMultiple: "first",
         requireChatGPT: true
-    });
-    if (userTab !== undefined) {
-        return userTab;
+    }, false).catch(() => ({ page: undefined }));
+    if (userTab.page !== undefined) {
+        return userTab.page;
     }
     const selected = browser.tabs?.selected;
     if (typeof selected === "function") {
@@ -282,8 +387,8 @@ async function findExistingChatGPTTab(browser) {
     return undefined;
 }
 class ExistingTabSelectionError extends ChatGPTControlError {
-    constructor(message, code, candidates = []) {
-        super(message, "not_found", true, undefined, {
+    constructor(message, code, candidates = [], diagnostics) {
+        const details = {
             code,
             candidates: candidates.map(tab => ({ label: userTabCandidateLabel(tab) })),
             remediation: [
@@ -298,7 +403,10 @@ class ExistingTabSelectionError extends ChatGPTControlError {
                     userActionRequired: false
                 }
             ]
-        });
+        };
+        if (diagnostics !== undefined)
+            details.diagnostics = { existingTab: diagnostics };
+        super(message, "not_found", true, undefined, details);
     }
 }
 function targetRequiresChatGPT(target) {

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/downloads.js

@@ -1,5 +1,6 @@
 import { mkdir, stat } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
+import { localGuardTimeout, withTimeout } from "../commands/timeouts.js";
 export async function waitForDownloadFromClick(page, click, destDir, timeoutMs) {
     const absoluteDest = resolve(destDir);
     await mkdir(absoluteDest, { recursive: true });
@@ -7,7 +8,7 @@ export async function waitForDownloadFromClick(page, click, destDir, timeoutMs)
     if (downloadPromise === undefined) {
         throw new Error("The active browser page does not expose download events.");
     }
-    await click();
+    await withTimeout(click(), localGuardTimeout(timeoutMs, 10000), "Download control click did not complete before the local guard timeout.");
     const download = await downloadPromise;
     const suggestedFilename = download.suggestedFilename?.() ?? `chatgpt-download-${Date.now()}`;
     const targetPath = join(absoluteDest, basename(suggestedFilename));

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

@@ -1,8 +1,20 @@
 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";
 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(() => "") : "";
@@ -32,7 +44,7 @@ export async function readPageState(page) {
 export async function readVisibleText(page) {
     if (typeof page.evaluate === "function") {
         try {
-            return await page.evaluate(() => document.body?.innerText ?? "");
+            return await withTimeout(page.evaluate(() => document.body?.innerText ?? ""), 1000, "Timed out while reading visible page text.");
         }
         catch {
             // Fall back to content parsing below.
@@ -40,7 +52,7 @@ export async function readVisibleText(page) {
     }
     if (typeof page.content === "function") {
         try {
-            const html = await page.content();
+            const html = await withTimeout(page.content(), 1000, "Timed out while reading page content.");
             return htmlToText(html);
         }
         catch {
@@ -62,5 +74,6 @@ export function htmlToText(html) {
         .trim();
 }
 function isLikelySignedIn(visibleText) {
-    return /\b(New chat|Search chats|Chat with ChatGPT|Recents|Projects)\b/i.test(visibleText);
+    const markers = localeLabels.signedInMarkers.map(escapeRegExp).join("|");
+    return new RegExp(`\\b(${markers})\\b`, "i").test(visibleText);
 }

package/dist/src/client.d.ts

@@ -1,10 +1,11 @@
-import type { AskArgs, AttachFilesArgs, BootstrapArgs, CommandResult, CopyResponseArgs, DownloadLatestArgs, NewThreadArgs, OpenThreadArgs, 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";
 import type { ChatGPTAgent, ChatGPTAgentConfig, ChatGPTResponse, ChatGPTRunner, ChatGPTRunInput, ChatGPTRunResult } from "./runner/types.js";
 import { type ChatGPTResponsesCreateArgs } from "./runner/responses.js";
 import { type ReportRedactionOptions } from "./safety/report-redaction.js";
+import { type BlockerExplanation, type ExplainBlockerOptions } from "./diagnostics/blockers.js";
 export type ChatGPTClientOptions = RuntimeEnv & {
     defaults?: {
         mode?: SetModeArgs;
@@ -112,9 +113,15 @@ export type ChatGPTClient = {
     readLatest(args?: ReadLatestArgs): Promise<CommandResult<unknown>>;
     copyLatest(args?: CopyResponseArgs): Promise<CommandResult<unknown>>;
     downloadLatest(args: DownloadLatestArgs): Promise<CommandResult<unknown>>;
+    artifacts: {
+        listLatest(args?: ListArtifactsArgs): Promise<CommandResult<unknown>>;
+        wait(args?: ArtifactWaitArgs): Promise<CommandResult<unknown>>;
+        downloadLatest(args: ArtifactDownloadArgs): Promise<CommandResult<unknown>>;
+    };
     runPlan(plan: SequencePlan | NamedWorkflowInvocation): Promise<CommandResult<unknown>>;
     doctor(args?: DoctorArgs): Promise<CommandResult<DoctorReport>>;
     createReport(result: CommandResult<unknown>, args?: RunReportOptions): Promise<CommandResult<RunReportData>>;
+    explainBlocker(resultOrBlocker: CommandResult<unknown> | NonNullable<CommandResult["blocker"]> | undefined, options?: ExplainBlockerOptions): BlockerExplanation;
     reports: {
         create(result: CommandResult<unknown>, args?: RunReportOptions): Promise<CommandResult<RunReportData>>;
         redact(value: unknown, args?: ReportRedactionOptions): Promise<CommandResult<unknown>>;
@@ -151,11 +158,20 @@ export type ChatGPTClient = {
         waitAndRead(args?: WaitArgs & ReadLatestArgs): Promise<CommandResult<unknown>>;
     };
     files: {
+        preflight(args: FilePreflightArgs): Promise<CommandResult<FilePreflightData>>;
         attach(args: AttachFilesArgs): Promise<CommandResult<unknown>>;
         downloadLatest(args: DownloadLatestArgs): Promise<CommandResult<unknown>>;
     };
+    projects: {
+        sources: {
+            list(args: ProjectSourcesListArgs): Promise<CommandResult<ProjectSourcesListData>>;
+            planAdd(args: ProjectSourcesPlanAddArgs): Promise<CommandResult<ProjectSourcesAddPlanData>>;
+            add(args: ProjectSourcesAddArgs): Promise<CommandResult<ProjectSourcesAddData | ProjectSourcesAddPlanData>>;
+        };
+    };
     modes: {
         set(args: SetModeArgs): Promise<CommandResult<unknown>>;
+        get(args?: GetModeArgs): Promise<CommandResult<GetModeData>>;
     };
     tools: {
         select(args: SelectToolArgs): Promise<CommandResult<unknown>>;