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

package/dist/src/client.js

@@ -1,7 +1,9 @@
-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";
+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";
@@ -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,11 +74,25 @@ 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)
+            set: args => setMode(env, args),
+            get: args => getMode(env, args)
         },
         tools: {
             select: args => selectTool(env, args)
@@ -88,6 +106,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 +154,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 +265,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 +280,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 +299,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 +469,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 +498,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>;

package/dist/src/commands/artifacts.js

@@ -0,0 +1,432 @@
+import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { waitForDownloadFromClick } from "../browser/downloads.js";
+import { readPageState } from "../browser/page-state.js";
+import { listPageArtifacts, readLatestImageDataUrl } from "../dom/artifacts.js";
+import { cssSelectors, requiredLocator } from "../dom/selectors.js";
+import { localeLabels } from "../dom/locale-labels.js";
+import { resultOk } from "../errors.js";
+import { contextFromPage } from "./context.js";
+import { bootstrap } from "./session.js";
+import { localGuardTimeout, withTimeout } from "./timeouts.js";
+export async function listLatestArtifacts(env, args = {}) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        const artifacts = await listPageArtifactsWithBridgeFallback(env, page, args);
+        return resultOk(artifactListData(artifacts), await contextFromPage(page));
+    }
+    catch (error) {
+        return artifactSelectorBlocker(error, await contextFromPage(page));
+    }
+}
+export async function waitForArtifact(env, args = {}) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    const timeoutMs = args.timeoutMs ?? 120000;
+    const stableMs = args.stableMs ?? 1000;
+    const pollMs = args.pollMs ?? 750;
+    const started = Date.now();
+    const afterArtifactCount = args.afterArtifactCount ?? 0;
+    let lastSignature = "";
+    let lastChangedAt = Date.now();
+    let latestArtifacts = [];
+    while (Date.now() - started < timeoutMs) {
+        const state = await withTimeout(readPageState(page), localGuardTimeout(timeoutMs, 5000), "Timed out while reading ChatGPT page state.").catch(() => undefined);
+        if (state?.blocker !== undefined && state.blocker.kind !== "modal") {
+            return {
+                ok: false,
+                status: "blocked",
+                warnings: [],
+                blocker: state.blocker,
+                context: await contextFromPage(page)
+            };
+        }
+        try {
+            latestArtifacts = await listPageArtifactsWithBridgeFallback(env, page, args);
+        }
+        catch (error) {
+            return artifactSelectorBlocker(error, await contextFromPage(page));
+        }
+        const latest = latestArtifacts.at(-1);
+        const signature = JSON.stringify({
+            count: latestArtifacts.length,
+            src: latest?.src,
+            width: latest?.width,
+            height: latest?.height,
+            downloadAvailable: latest?.downloadAvailable
+        });
+        if (signature !== lastSignature) {
+            lastSignature = signature;
+            lastChangedAt = Date.now();
+        }
+        const targetReached = latestArtifacts.length > afterArtifactCount
+            && latest !== undefined
+            && (args.requireDownload !== true || latest.downloadAvailable);
+        if (targetReached && Date.now() - lastChangedAt >= stableMs && !await hasStopControl(page, timeoutMs)) {
+            return resultOk({
+                complete: true,
+                count: latestArtifacts.length,
+                latest,
+                elapsedMs: Date.now() - started
+            }, await contextFromPage(page));
+        }
+        await sleep(page, pollMs);
+    }
+    const data = {
+        complete: false,
+        count: latestArtifacts.length,
+        elapsedMs: Date.now() - started
+    };
+    const latest = latestArtifacts.at(-1);
+    if (latest !== undefined)
+        data.latest = latest;
+    return {
+        ok: false,
+        status: "timeout",
+        data,
+        warnings: [],
+        blocker: {
+            kind: "artifact_unavailable",
+            code: args.requireDownload === true ? "artifact_download_not_ready" : "artifact_not_ready",
+            message: args.requireDownload === true
+                ? "No generated artifact with a visible download affordance appeared before the timeout."
+                : "No generated artifact appeared before the timeout.",
+            resumable: true
+        },
+        context: await contextFromPage(page)
+    };
+}
+export async function downloadLatestArtifact(env, args) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    const timeoutMs = args.timeoutMs ?? 120000;
+    if (args.prefer !== "visible_image_source") {
+        const byDownload = await tryDownloadControl(page, args, timeoutMs);
+        if (byDownload.ok || args.prefer === "download_control") {
+            return byDownload;
+        }
+    }
+    try {
+        const byImageSource = await saveLatestVisibleImageSource(page, args.destDir, timeoutMs);
+        if (byImageSource !== undefined) {
+            return resultOk(byImageSource, await contextFromPage(page));
+        }
+    }
+    catch (error) {
+        return artifactDownloadBlocker(error, await contextFromPage(page));
+    }
+    try {
+        const byPageAssets = await saveLatestPageAssetImage(env, page, args.destDir, timeoutMs);
+        if (byPageAssets !== undefined) {
+            return resultOk(byPageAssets, await contextFromPage(page));
+        }
+    }
+    catch (error) {
+        return artifactDownloadBlocker(error, await contextFromPage(page));
+    }
+    return artifactDownloadBlocker(new Error("No visible generated image source was available to save."), await contextFromPage(page));
+}
+export async function locatorCountWithTimeout(locator, timeoutMs, code) {
+    if (locator === undefined || typeof locator.count !== "function") {
+        return 0;
+    }
+    return withTimeout(locator.count(), timeoutMs, `${code}: locator count did not complete before the local guard timeout.`);
+}
+async function tryDownloadControl(page, args, timeoutMs) {
+    try {
+        const controls = requiredLocator(page, cssSelectors.generatedArtifactDownloadControls);
+        const count = await locatorCountWithTimeout(controls, localGuardTimeout(timeoutMs, 5000), "artifact_download_control_timeout");
+        if (count === 0) {
+            return artifactDownloadBlocker(new Error("No visible generated-image download control was found."), await contextFromPage(page));
+        }
+        const target = controls.last?.() ?? controls;
+        const downloaded = await waitForDownloadFromClick(page, async () => {
+            await target.click?.({ timeoutMs: localGuardTimeout(timeoutMs, 10000) });
+        }, args.destDir, timeoutMs);
+        return resultOk(downloaded, await contextFromPage(page));
+    }
+    catch (error) {
+        return artifactDownloadBlocker(error, await contextFromPage(page));
+    }
+}
+async function saveLatestVisibleImageSource(page, destDir, timeoutMs) {
+    const source = await readLatestImageDataUrl(page, timeoutMs);
+    if (source === undefined)
+        return undefined;
+    const parsed = parseDataUrl(source.dataUrl);
+    if (parsed === undefined)
+        return undefined;
+    const absoluteDest = resolve(destDir);
+    await mkdir(absoluteDest, { recursive: true });
+    const suggestedFilename = `generated-image-${Date.now()}.${extensionForMime(parsed.mimeType)}`;
+    const path = join(absoluteDest, suggestedFilename);
+    await writeFile(path, parsed.bytes);
+    const saved = await stat(path);
+    if (saved.size <= 0) {
+        throw new Error(`Generated image artifact file is empty: ${path}`);
+    }
+    return { path, suggestedFilename, bytes: saved.size };
+}
+async function listPageArtifactsWithBridgeFallback(env, page, args) {
+    try {
+        const artifacts = await listPageArtifacts(page, args);
+        if (artifacts.length > 0) {
+            return artifacts;
+        }
+        const fromAssets = await listPageAssetArtifacts(env, page, args, args.timeoutMs).catch(() => []);
+        return fromAssets.length > 0 ? fromAssets : artifacts;
+    }
+    catch (error) {
+        const fromAssets = await listPageAssetArtifacts(env, page, args, args.timeoutMs).catch(() => []);
+        if (fromAssets.length > 0) {
+            return fromAssets;
+        }
+        throw error;
+    }
+}
+async function listPageAssetArtifacts(env, page, args, timeoutMs) {
+    const inventory = await readPageAssetsInventory(page, timeoutMs).catch(() => undefined)
+        ?? await withTemporaryBridgeOwnedPage(env, page, timeoutMs, async (freshPage) => {
+            return await readPageAssetsInventory(freshPage, timeoutMs).catch(() => undefined);
+        });
+    if (inventory === undefined)
+        return [];
+    const artifacts = inventory.assets
+        .filter(asset => asset.kind === "image")
+        .filter(asset => !isInlineSvgAsset(asset) && isLikelyRasterImageAsset(asset))
+        .map((asset, index) => {
+        const artifact = {
+            kind: "image",
+            index,
+            visible: true,
+            downloadAvailable: true,
+            selectorProvenance: "pageAssets image inventory"
+        };
+        const src = safeArtifactSrc(asset.url);
+        if (src !== undefined)
+            artifact.src = src;
+        return artifact;
+    });
+    const max = args.max ?? artifacts.length;
+    return artifacts
+        .filter(artifact => artifact.kind === (args.kind ?? "image"))
+        .slice(-max)
+        .map((artifact, index) => ({ ...artifact, index }));
+}
+async function saveLatestPageAssetImage(env, page, destDir, timeoutMs) {
+    return await saveLatestPageAssetImageFromPage(page, destDir, timeoutMs).catch(() => undefined)
+        ?? await withTemporaryBridgeOwnedPage(env, page, timeoutMs, async (freshPage) => {
+            return await saveLatestPageAssetImageFromPage(freshPage, destDir, timeoutMs).catch(() => undefined);
+        });
+}
+async function saveLatestPageAssetImageFromPage(page, destDir, timeoutMs) {
+    const capability = await getPageAssetsCapability(page);
+    if (capability === undefined)
+        return undefined;
+    const inventory = await withTimeout(capability.list(), localGuardTimeout(timeoutMs, 15000), "Timed out while listing page assets for generated image download.");
+    const candidateIds = inventory.assets
+        .filter(asset => asset.kind === "image")
+        .filter(asset => !isInlineSvgAsset(asset) && isLikelyRasterImageAsset(asset))
+        .map(asset => asset.id);
+    if (candidateIds.length === 0)
+        return undefined;
+    const bundled = await withTimeout(capability.bundle({ assetIds: candidateIds, inventoryId: inventory.id, kinds: ["image"] }), localGuardTimeout(timeoutMs, 30000), "Timed out while bundling generated image page asset.");
+    const asset = bundled.assets
+        .filter(item => !isInlineSvgAsset(item) && isLikelyRasterImageAsset(item))
+        .at(-1);
+    if (asset === undefined)
+        return undefined;
+    const absoluteDest = resolve(destDir);
+    await mkdir(absoluteDest, { recursive: true });
+    const suggestedFilename = `generated-image-${Date.now()}.${extensionForMime(asset.contentType ?? "image/png")}`;
+    const path = join(absoluteDest, suggestedFilename);
+    await copyFile(asset.path, path);
+    const saved = await stat(path);
+    if (saved.size <= 0) {
+        throw new Error(`Generated image artifact file is empty: ${path}`);
+    }
+    return { path, suggestedFilename, bytes: saved.size };
+}
+async function readPageAssetsInventory(page, timeoutMs) {
+    const capability = await getPageAssetsCapability(page);
+    if (capability === undefined)
+        return undefined;
+    return await withTimeout(capability.list(), localGuardTimeout(timeoutMs, 15000), "Timed out while listing page assets for generated artifacts.");
+}
+async function getPageAssetsCapability(page) {
+    const capabilities = page.capabilities;
+    const get = capabilities?.get;
+    if (typeof get !== "function")
+        return undefined;
+    const capability = await get.call(capabilities, "pageAssets");
+    if (!isPageAssetsCapability(capability))
+        return undefined;
+    return capability;
+}
+async function withTemporaryBridgeOwnedPage(env, currentPage, timeoutMs, callback) {
+    const url = await currentPageUrl(currentPage);
+    if (url === undefined || !/^https:\/\/chatgpt\.com\/c\//i.test(url))
+        return undefined;
+    const freshPage = await openTemporaryPage(env, url, timeoutMs);
+    if (freshPage === undefined)
+        return undefined;
+    try {
+        await settlePage(freshPage, localGuardTimeout(timeoutMs, 5000));
+        return await callback(freshPage);
+    }
+    finally {
+        await closeTemporaryPage(freshPage).catch(() => undefined);
+    }
+}
+async function openTemporaryPage(env, url, timeoutMs) {
+    const browser = env.browser;
+    if (browser === undefined)
+        return undefined;
+    let page;
+    if (typeof browser.tabs?.create === "function") {
+        page = await Promise.resolve(browser.tabs.create.call(browser.tabs, url));
+    }
+    else if (typeof browser.tabs?.new === "function") {
+        page = await Promise.resolve(browser.tabs.new.call(browser.tabs));
+        if (typeof page?.goto === "function") {
+            await withTimeout(page.goto(url), localGuardTimeout(timeoutMs, 20000), "Timed out while opening generated image conversation in a temporary bridge tab.").catch(() => undefined);
+        }
+    }
+    else if (typeof browser.newPage === "function") {
+        page = await Promise.resolve(browser.newPage.call(browser));
+        if (typeof page?.goto === "function") {
+            await withTimeout(page.goto(url), localGuardTimeout(timeoutMs, 20000), "Timed out while opening generated image conversation in a temporary bridge page.").catch(() => undefined);
+        }
+    }
+    return page;
+}
+async function settlePage(page, timeoutMs) {
+    const waitForTimeout = page.waitForTimeout ?? page.playwright?.waitForTimeout;
+    if (typeof waitForTimeout !== "function")
+        return;
+    await withTimeout(waitForTimeout.call(page.waitForTimeout === waitForTimeout ? page : page.playwright, Math.min(timeoutMs, 5000)), timeoutMs, "Timed out while waiting for temporary bridge tab to settle.").catch(() => undefined);
+}
+async function closeTemporaryPage(page) {
+    if (typeof page.close === "function") {
+        await page.close();
+    }
+}
+async function currentPageUrl(page) {
+    const value = await Promise.resolve(page.url?.()).catch(() => undefined);
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isPageAssetsCapability(value) {
+    return typeof value === "object"
+        && value !== null
+        && typeof value.list === "function"
+        && typeof value.bundle === "function";
+}
+function isLikelyRasterImageAsset(asset) {
+    const contentType = asset.contentType ?? "";
+    if (/^image\/(png|jpe?g|webp|gif|avif)$/i.test(contentType))
+        return true;
+    const name = asset.name ?? basename(asset.path ?? "");
+    const url = asset.url ?? "";
+    return /\.(png|jpe?g|webp|gif|avif)(?:$|[?#])/i.test(name)
+        || /\.(png|jpe?g|webp|gif|avif)(?:$|[?#])/i.test(url)
+        || (contentType === "" && !isInlineSvgAsset(asset));
+}
+function isInlineSvgAsset(asset) {
+    return /^inline-svg:/i.test(asset.url ?? "")
+        || /svg/i.test(asset.contentType ?? "")
+        || /\.svg(?:$|[?#])/i.test(asset.name ?? "")
+        || /\.svg(?:$|[?#])/i.test(asset.path ?? "");
+}
+function safeArtifactSrc(src) {
+    if (src === undefined)
+        return undefined;
+    if (/^https:\/\/chatgpt\.com\/backend-api\/estuary\/content\b/i.test(src)) {
+        return undefined;
+    }
+    return src;
+}
+function parseDataUrl(dataUrl) {
+    const match = /^data:([^;,]+);base64,(.*)$/i.exec(dataUrl);
+    if (match === null || match[1] === undefined || match[2] === undefined)
+        return undefined;
+    return { mimeType: match[1], bytes: Buffer.from(match[2], "base64") };
+}
+function extensionForMime(mimeType) {
+    if (/jpeg|jpg/i.test(mimeType))
+        return "jpg";
+    if (/webp/i.test(mimeType))
+        return "webp";
+    if (/gif/i.test(mimeType))
+        return "gif";
+    return "png";
+}
+function artifactListData(artifacts) {
+    const data = {
+        count: artifacts.length,
+        artifacts
+    };
+    const latest = artifacts.at(-1);
+    if (latest !== undefined)
+        data.latest = latest;
+    return data;
+}
+function artifactSelectorBlocker(error, context) {
+    return {
+        ok: false,
+        status: "blocked",
+        warnings: [],
+        blocker: {
+            kind: "artifact_selector_drift",
+            code: "artifact_dom_timeout",
+            message: `Generated artifact detection could not inspect the ChatGPT page: ${error instanceof Error ? error.message : String(error)}`,
+            resumable: true
+        },
+        context
+    };
+}
+function artifactDownloadBlocker(error, context) {
+    return {
+        ok: false,
+        status: "unsupported",
+        warnings: [],
+        blocker: {
+            kind: "artifact_download_unavailable",
+            code: "artifact_download_unavailable",
+            message: `No downloadable generated artifact could be saved from the visible ChatGPT page: ${error instanceof Error ? error.message : String(error)}`,
+            resumable: true
+        },
+        context
+    };
+}
+async function ensurePage(env) {
+    if (env.page !== undefined) {
+        return resultOk({}, await contextFromPage(env.page));
+    }
+    return bootstrap(env, { preferExistingTab: true });
+}
+async function hasStopControl(page, timeoutMs) {
+    if (typeof page.evaluate !== "function")
+        return false;
+    return withTimeout(page.evaluate((phrases) => {
+        const text = document.body?.innerText ?? "";
+        const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return phrases.some(phrase => new RegExp(`\\b${escape(phrase)}\\b`, "i").test(text));
+    }, [...localeLabels.stopControl]), localGuardTimeout(timeoutMs, 2000), "Timed out while checking ChatGPT stop controls.").catch(() => false);
+}
+async function sleep(page, ms) {
+    if (typeof page.waitForTimeout === "function") {
+        await page.waitForTimeout(ms);
+        return;
+    }
+    await new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/src/commands/context.js

@@ -1,13 +1,18 @@
 import { countPageMessages } from "../dom/messages.js";
 import { parseConversationId } from "../browser/page-state.js";
+import { withTimeout } from "./timeouts.js";
 export async function contextFromPage(page, partial = {}) {
     if (page === undefined) {
         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 turnCount = await countPageMessages(page).catch(() => partial.turnCount);
-    const assistantTurnCount = await countPageMessages(page, "assistant").catch(() => partial.assistantTurnCount);
+    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)
+    ]);
     const conversationId = url !== undefined ? parseConversationId(url) : partial.conversationId;
     const context = {
         timestamp: new Date().toISOString(),

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>;