codex-chatgpt-control 0.1.0-alpha.1 → 0.2.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", "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,8 +37,15 @@ 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",
     "tools.select",
     "response.copy"

package/dist/src/backend/session.js

@@ -141,10 +141,24 @@ 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 "tools.select":

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/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,5 +1,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";
 export function parseConversationId(url) {
     const match = /\/c\/([A-Za-z0-9-]+)/.exec(url);
     return match?.[1];
@@ -32,7 +34,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 +42,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 +64,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, 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,9 +158,17 @@ 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>>;
     };

package/dist/src/client.js

@@ -1,4 +1,6 @@
-import { attachFiles, downloadLatestFile } from "./commands/files.js";
+import { downloadLatestArtifact, listLatestArtifacts, waitForArtifact } from "./commands/artifacts.js";
+import { attachFiles, downloadLatestFile, preflightFiles } from "./commands/files.js";
+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";
@@ -14,6 +16,7 @@ import { toRunResult } from "./runner/result.js";
 import { responseFromRunResult, responsesCreateArgsToRunInput, unsupportedResponse, validateResponsesCreateArgs } from "./runner/responses.js";
 import { streamFromRunResult } from "./runner/stream.js";
 import { redactReportValue } from "./safety/report-redaction.js";
+import { explainCommandBlocker } from "./diagnostics/blockers.js";
 export function createChatGPT(options = {}) {
     const env = runtimeEnv(options);
     const limits = normalizeLimits(options.limits);
@@ -44,6 +47,7 @@ export function createChatGPT(options = {}) {
         runPlan: plan => runPlanInvocation(plan, env, limits, options.defaults, options.reporting),
         doctor: args => doctor(env, args),
         createReport: (result, args) => createRunReport(env, result, args ?? options.reporting ?? {}),
+        explainBlocker: (resultOrBlocker, args) => explainCommandBlocker(resultOrBlocker, args),
         reports: {
             create: (result, args) => createRunReport(env, result, args ?? options.reporting ?? {}),
             redact: async (value, args) => resultOk(redactReportValue(value, args), {}),
@@ -70,9 +74,22 @@ export function createChatGPT(options = {}) {
             waitAndRead: args => waitAndRead(env, args)
         },
         files: {
+            preflight: args => preflightFiles(env, args),
             attach: args => attachFiles(env, args),
             downloadLatest: args => downloadLatestFile(env, args)
         },
+        projects: {
+            sources: {
+                list: args => listProjectSources(env, args),
+                planAdd: args => buildProjectSourceAddPlan(env, args),
+                add: args => addProjectSources(env, args)
+            }
+        },
+        artifacts: {
+            listLatest: args => listLatestArtifacts(env, args),
+            wait: args => waitForArtifact(env, args),
+            downloadLatest: args => downloadLatestArtifact(env, args)
+        },
         modes: {
             set: args => setMode(env, args)
         },
@@ -88,6 +105,9 @@ async function runGuarded(plan, env, limits, report) {
     const budget = checkRunBudget(plan, limits);
     if (budget !== undefined)
         return budget;
+    const filePreflight = await preflightPlanFiles(plan, env);
+    if (filePreflight !== undefined)
+        return filePreflight;
     const result = await runSequence(plan, env);
     if (report === undefined || report.enabled === false)
         return result;
@@ -133,6 +153,18 @@ async function runGuarded(plan, env, limits, report) {
         ]
     };
 }
+async function preflightPlanFiles(plan, env) {
+    const paths = plan.steps
+        .flatMap(step => step.command === "files.attach" ? pathsFromAttachStep(step) : []);
+    if (paths.length === 0)
+        return undefined;
+    const result = await preflightFiles(env, { paths });
+    return result.ok ? undefined : result;
+}
+function pathsFromAttachStep(step) {
+    const paths = step.args.paths;
+    return paths.every(item => typeof item === "string") ? paths : [];
+}
 function normalizeLimits(limits) {
     return {
         maxPromptsPerRun: limits?.maxPromptsPerRun ?? 5,
@@ -232,6 +264,7 @@ function planAgentWorkflowFromNormalized(agent, input, defaults = {}) {
     const wait = input.wait ?? agent.defaults.wait ?? defaults.wait ?? true;
     const read = input.read ?? agent.defaults.read ?? defaults.read ?? { format: "markdown" };
     const thread = input.thread ?? agent.defaults.thread ?? { type: "new" };
+    const artifactDownload = input.download !== undefined && input.download !== false && usesCreateImageTool(input.tools);
     const steps = [
         bootstrapStepForWorkflow(thread, input.existingTab ?? agent.defaults.existingTab ?? defaults.existingTab, input.preferExistingTab ?? agent.defaults.preferExistingTab ?? defaults.preferExistingTab),
         ...threadSteps(thread)
@@ -246,6 +279,9 @@ function planAgentWorkflowFromNormalized(agent, input, defaults = {}) {
     if (input.files.length > 0) {
         steps.push({ id: "attach", command: "files.attach", args: { paths: input.files } });
     }
+    if (artifactDownload) {
+        steps.push({ id: "artifactBaseline", command: "artifacts.listLatest", args: { kind: "image" } });
+    }
     if (agent.instructionsMode === "visible_setup_message" && hasInstructions(agent)) {
         steps.push({
             id: "agent_setup",
@@ -262,15 +298,22 @@ function planAgentWorkflowFromNormalized(agent, input, defaults = {}) {
         command: "messages.ask",
         args: {
             text: renderRunnerPrompt(agent, input.prompt),
-            wait,
-            read
+            wait: artifactDownload ? false : wait,
+            read: artifactDownload ? false : read
         }
     });
+    if (artifactDownload) {
+        steps.push({
+            id: "artifact",
+            command: "artifacts.wait",
+            args: artifactWaitArgs(wait, input.download === false ? undefined : input.download)
+        });
+    }
     if (input.copy !== undefined && input.copy !== false) {
         steps.push({ id: "copy", command: "response.copy", args: input.copy });
     }
     if (input.download !== undefined && input.download !== false) {
-        steps.push({ id: "download", command: "files.downloadLatest", args: input.download });
+        steps.push({ id: "download", command: artifactDownload ? "artifacts.downloadLatest" : "files.downloadLatest", args: input.download });
     }
     return {
         name: `agent-run:${agent.name}`,
@@ -425,17 +468,28 @@ function planAskWorkflow(args, defaults = {}) {
     if (files.length > 0) {
         steps.push({ id: "attach", command: "files.attach", args: { paths: files } });
     }
+    const artifactDownload = args.download !== undefined && usesCreateImageTool(args.tools ?? []);
+    if (artifactDownload) {
+        steps.push({ id: "artifactBaseline", command: "artifacts.listLatest", args: { kind: "image" } });
+    }
     steps.push({
         id: "ask",
         command: "messages.ask",
         args: {
             text: args.prompt,
-            wait: args.wait ?? defaults.wait ?? true,
-            read: args.read ?? defaults.read ?? { format: "markdown" }
+            wait: artifactDownload ? false : args.wait ?? defaults.wait ?? true,
+            read: artifactDownload ? false : args.read ?? defaults.read ?? { format: "markdown" }
         }
     });
     if (args.download !== undefined) {
-        steps.push({ id: "download", command: "files.downloadLatest", args: args.download });
+        if (artifactDownload) {
+            steps.push({
+                id: "artifact",
+                command: "artifacts.wait",
+                args: artifactWaitArgs(args.wait ?? defaults.wait ?? true, args.download)
+            });
+        }
+        steps.push({ id: "download", command: artifactDownload ? "artifacts.downloadLatest" : "files.downloadLatest", args: args.download });
     }
     return {
         name: args.download === undefined ? "ask" : "ask-and-download",
@@ -443,6 +497,31 @@ function planAskWorkflow(args, defaults = {}) {
         steps
     };
 }
+function usesCreateImageTool(tools) {
+    return tools.some(tool => normalizeToolName(tool.tool) === "create_image");
+}
+function normalizeToolName(tool) {
+    return tool.trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+function artifactWaitArgs(wait, download) {
+    const args = {
+        kind: "image",
+        afterArtifactCount: "${artifactBaseline.data.count}",
+        requireDownload: true
+    };
+    if (typeof wait === "object") {
+        if (wait.timeoutMs !== undefined)
+            args.timeoutMs = wait.timeoutMs;
+        if (wait.stableMs !== undefined)
+            args.stableMs = wait.stableMs;
+        if (wait.pollMs !== undefined)
+            args.pollMs = wait.pollMs;
+    }
+    if (args.timeoutMs === undefined && download?.timeoutMs !== undefined) {
+        args.timeoutMs = download.timeoutMs;
+    }
+    return args;
+}
 function planRunMessages(args, defaults = {}) {
     const thread = args.thread ?? { type: "new" };
     const steps = [

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

@@ -0,0 +1,5 @@
+import type { ArtifactDownloadArgs, ArtifactListData, ArtifactWaitArgs, ArtifactWaitData, CommandResult, DownloadedFile, ListArtifactsArgs, LocatorLike, RuntimeEnv } from "../types.js";
+export declare function listLatestArtifacts(env: RuntimeEnv, args?: ListArtifactsArgs): Promise<CommandResult<ArtifactListData>>;
+export declare function waitForArtifact(env: RuntimeEnv, args?: ArtifactWaitArgs): Promise<CommandResult<ArtifactWaitData>>;
+export declare function downloadLatestArtifact(env: RuntimeEnv, args: ArtifactDownloadArgs): Promise<CommandResult<DownloadedFile>>;
+export declare function locatorCountWithTimeout(locator: LocatorLike | undefined, timeoutMs: number, code: string): Promise<number>;