codex-chatgpt-control 0.1.0-alpha.1

package/dist/src/commands/modes.js

@@ -0,0 +1,323 @@
+import { resultError, resultOk } from "../errors.js";
+import { enumerateVisibleMenuItems, findUniqueMenuItem } from "../dom/menus.js";
+import { normalizeLabel, normalizeWhitespace } from "../dom/visible-text.js";
+import { contextFromPage } from "./context.js";
+import { bootstrap } from "./session.js";
+const DEFAULT_MODE_EFFORT = "Thinking";
+const CURRENT_MODE_LABELS = ["Latest", "Instant", "Thinking", "Extended", "Pro"];
+const MODE_OPENER_LABELS = [...CURRENT_MODE_LABELS.filter(label => label !== "Pro"), "Configure"];
+export async function setMode(env, args) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        const requested = requestedModeLabels(args);
+        const opened = await waitForModeMenu(page, requested, args.timeoutMs ?? 30000);
+        if (opened.alreadySelected.length === requested.length) {
+            return resultOk({ selected: opened.alreadySelected, candidates: opened.modeButtons }, await contextFromPage(page));
+        }
+        if (!opened.opened) {
+            return selectorDrift(page, "No unique ChatGPT mode menu opener was found.");
+        }
+        await page.waitForTimeout?.(250);
+        const candidates = await enumerateVisibleMenuItems(page);
+        const selected = [];
+        for (const item of requested) {
+            const match = findUniqueMenuItem(candidates, item);
+            if (match === undefined) {
+                const candidateLabels = candidates.map(candidate => candidate.label);
+                return {
+                    ok: false,
+                    status: "unsupported",
+                    warnings: [],
+                    blocker: selectorDriftBlocker(`Mode option "${item}" was not found or was ambiguous.`, candidateLabels),
+                    context: await contextFromPage(page)
+                };
+            }
+            if (!await clickMenuItem(page, match.label)) {
+                return selectorDrift(page, `Mode option "${match.label}" was visible but could not be clicked.`, candidates.map(candidate => candidate.label));
+            }
+            selected.push(match.label);
+        }
+        return resultOk({ selected, candidates: candidates.map(candidate => candidate.label) }, await contextFromPage(page));
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+async function waitForModeMenu(page, requested, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let modeButtons = [];
+    do {
+        modeButtons = await visibleModeButtonLabelList(page);
+        const alreadySelected = findAlreadySelectedModes(modeButtons, requested);
+        if (alreadySelected.length === requested.length) {
+            return { opened: false, alreadySelected, modeButtons };
+        }
+        const openMenuItems = await enumerateVisibleMenuItems(page);
+        if (looksLikeModeMenu(openMenuItems.map(item => item.label))) {
+            return { opened: true, alreadySelected: [], modeButtons };
+        }
+        if (await clickModeOpener(page, modeButtons)) {
+            return { opened: true, alreadySelected: [], modeButtons };
+        }
+        if (Date.now() >= deadline) {
+            break;
+        }
+        await page.waitForTimeout?.(250);
+    } while (true);
+    return { opened: false, alreadySelected: [], modeButtons };
+}
+export async function selectTool(env, args) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        const opened = await clickFirstUniqueButton(page, ["Add files and more", "Add files", "Add photos"]);
+        if (!opened) {
+            return selectorDrift(page, "No unique ChatGPT tool menu opener was found.");
+        }
+        await page.waitForTimeout?.(250);
+        const candidates = await enumerateVisibleMenuItems(page);
+        const wanted = toolLabel(args.tool);
+        const match = findUniqueMenuItem(candidates, wanted);
+        if (match === undefined) {
+            const candidateLabels = candidates.map(candidate => candidate.label);
+            return {
+                ok: false,
+                status: "unsupported",
+                warnings: [],
+                blocker: selectorDriftBlocker(`Tool "${wanted}" was not found or was ambiguous.`, candidateLabels),
+                context: await contextFromPage(page)
+            };
+        }
+        if (!await clickMenuItem(page, match.label)) {
+            return selectorDrift(page, `Tool "${match.label}" was visible but could not be clicked.`, candidates.map(candidate => candidate.label));
+        }
+        return resultOk({ selected: match.label, candidates: candidates.map(candidate => candidate.label) }, await contextFromPage(page));
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+async function ensurePage(env) {
+    if (env.page !== undefined) {
+        return resultOk({}, await contextFromPage(env.page));
+    }
+    return bootstrap(env, { preferExistingTab: true });
+}
+async function clickFirstUniqueButton(page, labels) {
+    for (const label of labels) {
+        const roleLocator = page.getByRole?.("button", { name: label, exact: true });
+        if (await clickIfUnique(roleLocator)) {
+            return true;
+        }
+        const textLocator = page.locator?.("button, [role='button']")?.filter?.({ hasText: label });
+        if (await clickIfUnique(textLocator)) {
+            return true;
+        }
+    }
+    return false;
+}
+async function clickModeOpener(page, modeButtons) {
+    if (await clickFirstUniqueButton(page, modeButtons)) {
+        return true;
+    }
+    return clickFirstUniqueButton(page, MODE_OPENER_LABELS);
+}
+function looksLikeModeMenu(labels) {
+    return labels.some(label => {
+        const normalized = normalizeLabel(label);
+        return CURRENT_MODE_LABELS.some(modeLabel => visibleLabelMatches(normalized, normalizeLabel(modeLabel)));
+    });
+}
+async function clickMenuItem(page, label) {
+    if (await clickModelSwitcherMenuItem(page, label)) {
+        return true;
+    }
+    if (await clickMenuItemByDom(page, label)) {
+        return true;
+    }
+    const roleLocator = page.locator?.("[role='menuitem'], [role='menuitemradio'], [role='option']")?.filter?.({ hasText: label });
+    if (await clickIfUnique(roleLocator)) {
+        return true;
+    }
+    const textLocator = page.getByText?.(label, { exact: true });
+    return clickIfUnique(textLocator);
+}
+async function clickModelSwitcherMenuItem(page, label) {
+    if (typeof page.evaluate !== "function" || typeof page.locator !== "function") {
+        return false;
+    }
+    const testId = await page.evaluate((wanted) => {
+        const normalizedWanted = wanted.replace(/\s+/g, " ").trim().toLowerCase();
+        const candidates = Array.from(document.querySelectorAll("[data-testid^='model-switcher-']"));
+        const matches = candidates
+            .filter(node => {
+            const element = node;
+            const candidateTestId = element.getAttribute("data-testid") ?? "";
+            if (candidateTestId.endsWith("-effort"))
+                return false;
+            const text = (element.innerText ?? element.textContent ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+            return text === normalizedWanted;
+        })
+            .map(node => node.getAttribute("data-testid"))
+            .filter((value) => value !== null);
+        return matches.length === 1 ? matches[0] : undefined;
+    }, label).catch(() => undefined);
+    if (testId === undefined) {
+        return false;
+    }
+    return clickIfUnique(page.locator(`[data-testid="${escapeAttributeValue(testId)}"]`));
+}
+async function clickMenuItemByDom(page, label) {
+    if (typeof page.evaluate !== "function") {
+        return false;
+    }
+    return page.evaluate((wanted) => {
+        const normalizedWanted = wanted.replace(/\s+/g, " ").trim().toLowerCase();
+        const candidates = Array.from(document.querySelectorAll("[role='menuitem'], [role='menuitemradio'], [role='option']"));
+        const matches = candidates.filter(node => {
+            const element = node;
+            const text = (element.innerText ?? element.textContent ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+            return text === normalizedWanted;
+        });
+        if (matches.length !== 1)
+            return false;
+        matches[0].click();
+        return true;
+    }, label).catch(() => false);
+}
+async function clickIfUnique(locator) {
+    if (locator === undefined || typeof locator.count !== "function" || typeof locator.click !== "function") {
+        return false;
+    }
+    const count = await locator.count().catch(() => 0);
+    if (count !== 1) {
+        return false;
+    }
+    await locator.click();
+    return true;
+}
+function toolLabel(tool) {
+    switch (tool) {
+        case "web_search":
+            return "Web search";
+        case "deep_research":
+            return "Deep research";
+        case "create_image":
+            return "Create image";
+        default:
+            return tool;
+    }
+}
+function requestedModeLabels(args) {
+    const requested = [args.model, args.effort].filter((value) => value !== undefined);
+    return requested.length > 0 ? requested : [DEFAULT_MODE_EFFORT];
+}
+function findUniqueVisibleLabel(labels, wanted) {
+    const normalized = normalizeLabel(wanted);
+    const exact = labels.filter(label => normalizeLabel(label) === normalized);
+    if (exact.length === 1) {
+        return exact[0];
+    }
+    const fuzzy = labels.filter(label => visibleLabelMatches(normalizeLabel(label), normalized));
+    return fuzzy.length === 1 ? fuzzy[0] : undefined;
+}
+function visibleLabelMatches(label, wanted) {
+    if (wanted.length <= 3) {
+        return new RegExp(`(^|[^a-z0-9])${escapeRegExp(wanted)}([^a-z0-9]|$)`, "i").test(label);
+    }
+    return label.includes(wanted);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function escapeAttributeValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+function findAlreadySelectedModes(visibleButtons, requested) {
+    return requested
+        .map(label => findUniqueVisibleLabel(visibleButtons, label))
+        .filter((label) => label !== undefined);
+}
+async function selectorDrift(page, message, candidates) {
+    const visibleText = candidates?.join("\n") ?? await visibleButtonLabels(page);
+    return {
+        ok: false,
+        status: "unsupported",
+        warnings: [],
+        blocker: selectorDriftBlocker(message, candidates, visibleText),
+        context: await contextFromPage(page)
+    };
+}
+function selectorDriftBlocker(message, candidates, visibleText = candidates?.join("\n") ?? "") {
+    const candidateLabels = candidates ?? visibleText.split("\n").map(label => label.trim()).filter(Boolean).slice(0, 30);
+    const blocker = {
+        kind: "selector_drift",
+        code: "visible_candidate_not_found",
+        message,
+        visibleText,
+        resumable: false
+    };
+    if (candidateLabels.length > 0) {
+        blocker.candidates = candidateLabels.map(label => ({ label }));
+    }
+    return blocker;
+}
+async function visibleButtonLabels(page) {
+    return (await visibleButtonLabelList(page)).join("\n");
+}
+async function visibleButtonLabelList(page) {
+    if (typeof page.evaluate !== "function") {
+        return [];
+    }
+    return page.evaluate(() => {
+        return Array.from(document.querySelectorAll("button, [role='button']"))
+            .map(node => {
+            const element = node;
+            return element.getAttribute("aria-label") ?? element.innerText ?? element.textContent ?? "";
+        })
+            .map(text => text.trim())
+            .filter(Boolean)
+            .slice(0, 30);
+    }).then(labels => labels.map(normalizeWhitespace)).catch(() => []);
+}
+async function visibleModeButtonLabelList(page) {
+    if (typeof page.evaluate !== "function") {
+        return [];
+    }
+    return page.evaluate((modeLabels) => {
+        const normalizedModeLabels = modeLabels.map(label => label.toLowerCase());
+        const tokenMatches = (text, token) => {
+            if (token.length <= 3) {
+                return new RegExp(`(^|[^a-z0-9])${token}([^a-z0-9]|$)`, "i").test(text);
+            }
+            return text.includes(token);
+        };
+        return Array.from(document.querySelectorAll("button, [role='button']"))
+            .map(node => {
+            const element = node;
+            const visibleText = (element.innerText ?? element.textContent ?? "").replace(/\s+/g, " ").trim();
+            const ariaLabel = (element.getAttribute("aria-label") ?? "").replace(/\s+/g, " ").trim();
+            const label = visibleText.length > 0 ? visibleText : ariaLabel;
+            const testId = element.getAttribute("data-testid") ?? "";
+            if (testId === "accounts-profile-button")
+                return "";
+            if (/open profile menu/i.test(label))
+                return "";
+            if (visibleText.length === 0 && /feedback|conversation options|dismiss/i.test(ariaLabel))
+                return "";
+            const normalized = label.toLowerCase();
+            if (!normalizedModeLabels.some(modeLabel => tokenMatches(normalized, modeLabel)))
+                return "";
+            return label;
+        })
+            .filter(Boolean)
+            .slice(0, 30);
+    }, CURRENT_MODE_LABELS).then(labels => labels.map(normalizeWhitespace)).catch(() => []);
+}

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

@@ -0,0 +1,5 @@
+export declare function commandOutputText(data: unknown): string | undefined;
+export declare function withCommandOutputText<T extends {
+    data?: unknown;
+    output_text?: string;
+}>(result: T): T;

package/dist/src/commands/output.js

@@ -0,0 +1,31 @@
+export function commandOutputText(data) {
+    if (!isRecord(data))
+        return undefined;
+    const responseText = data.responseText;
+    if (typeof responseText === "string")
+        return responseText;
+    const role = data.role;
+    const text = data.text;
+    if (typeof text === "string" && role !== "user")
+        return text;
+    const markdown = data.markdown;
+    if (typeof markdown === "string")
+        return markdown;
+    for (const [key, value] of Object.entries(data)) {
+        if (key === "prompt" || key === "input")
+            continue;
+        const nested = commandOutputText(value);
+        if (nested !== undefined)
+            return nested;
+    }
+    return undefined;
+}
+export function withCommandOutputText(result) {
+    if (result.output_text !== undefined)
+        return result;
+    const outputText = commandOutputText(result.data);
+    return outputText === undefined ? result : { ...result, output_text: outputText };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,17 @@
+import { type RiskLevel } from "../safety/risk.js";
+export type CommandLayer = "workflow" | "primitive" | "diagnostic" | "report";
+export type CommandDescriptor = {
+    name: string;
+    layer: CommandLayer;
+    summary: string;
+    risk: RiskLevel;
+    defaultTimeoutMs?: number;
+    args: Record<string, string>;
+    defaults: Record<string, unknown>;
+    retryPolicy: string;
+    blockers: string[];
+    examples: string[];
+};
+export declare function commandDescriptors(): CommandDescriptor[];
+export declare function describeCommand(name: string): CommandDescriptor | undefined;
+export declare function helpText(topic?: string): string;

package/dist/src/commands/registry.js

@@ -0,0 +1,275 @@
+import { riskForCommand } from "../safety/risk.js";
+const descriptors = [
+    workflow("ask", "Ask ChatGPT in a new or selected thread, optionally with files, wait/read, downloads, and reports.", [
+        `await chatgpt.ask({ prompt: "reply with the word hi", wait: true, read: true });`
+    ]),
+    workflow("askInThread", "Open or claim an existing thread by URL, conversation id, title, or search query, then ask and read.", [
+        `await chatgpt.askInThread({ thread: { type: "search", query: "Naming macOS Utility" }, prompt: "Continue." });`,
+        `await chatgpt.askInThread({ thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true, prompt: "Continue." });`
+    ]),
+    workflow("askWithFiles", "Attach absolute local file paths, optionally set mode, ask, wait, and read.", [
+        `await chatgpt.askWithFiles({ thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true, mode: { effort: "Thinking" }, files: ["/absolute/path/brief.md"], prompt: "Summarize this.", wait: true, read: { format: "markdown" } });`
+    ]),
+    workflow("askAndDownload", "Ask ChatGPT to produce a visible downloadable output and save the latest exposed file.", [
+        `await chatgpt.askAndDownload({ prompt: "Create a CSV.", download: { destDir: "/tmp/out" }, wait: true });`
+    ]),
+    workflow("runMessages", "Run sequential prompts where later prompts can use earlier step data.", [
+        `await chatgpt.runMessages({ messages: [{ id: "first", prompt: "alpha" }, { id: "second", prompt: "beta" }] });`
+    ]),
+    workflow("runner.run", "Agents-style facade: run a visible ChatGPT browser-control agent against input, files, thread, existing-tab, mode, and response options.", [
+        `const agent = chatgpt.agent({ name: "reviewer", instructions: "Review deeply." }); await chatgpt.runner.run(agent, { input: "Review this.", thread: { type: "new" } });`,
+        `await chatgpt.runner.run(agent, { input: "Continue.", thread: { type: "url", url: "https://chatgpt.com/c/<conversation-id>" }, existingTab: true });`
+    ]),
+    workflow("responses.create", "Narrow Responses-shaped adapter over the visible ChatGPT browser-control runner; rejects unsupported API-only fields before prompt submission.", [
+        `await chatgpt.responses.create({ input: "Summarize.", thread: { type: "current" }, text: { format: "markdown" }, stream: false });`
+    ]),
+    workflow("copyLatest", "Copy or DOM-read the latest assistant response with Markdown-first fidelity.", [
+        `await chatgpt.copyLatest({ prefer: "clipboard" });`
+    ]),
+    workflow("runPlan", "Execute an inline SequencePlan or named macro through the existing sequence engine.", [
+        `await chatgpt.runPlan({ name: "new-ask-read", input: { prompt: "hi" } });`
+    ]),
+    workflow("new-ask-read", "Named macro: open a new thread, ask, wait, and read Markdown.", [
+        `await chatgpt.runPlan({ name: "new-ask-read", input: { prompt: "hi" } });`
+    ]),
+    workflow("find-open-ask-read", "Named macro: search history, open the first match, ask, wait, and read Markdown.", [
+        `await chatgpt.runPlan({ name: "find-open-ask-read", input: { query: "SDK Design Proposal", prompt: "Continue." } });`
+    ]),
+    workflow("find-open-copy-latest", "Named macro: search history, open the first match, and copy/read the latest response.", [
+        `await chatgpt.runPlan({ name: "find-open-copy-latest", input: { query: "SDK Design Proposal" } });`
+    ]),
+    workflow("attach-ask-read", "Named macro: open a new thread, attach files, ask, wait, and read Markdown.", [
+        `await chatgpt.runPlan({ name: "attach-ask-read", input: { files: ["/absolute/path.md"], prompt: "Summarize." } });`
+    ]),
+    workflow("ask-and-download", "Named macro: ask in a new thread and download the latest file affordance.", [
+        `await chatgpt.runPlan({ name: "ask-and-download", input: { prompt: "Create a CSV.", destDir: "/tmp/out" } });`
+    ]),
+    workflow("two-turn", "Named macro: run two sequential prompts in a new thread.", [
+        `await chatgpt.runPlan({ name: "two-turn", input: { first: "alpha", second: "beta" } });`
+    ]),
+    diagnostic("doctor-upload", "Named macro: preflight bridge, login, and upload permission remediation.", [
+        `await chatgpt.runPlan({ name: "doctor-upload" });`
+    ]),
+    report("redacted-run-report", "Named macro: create a redacted report for a supplied CommandResult.", [
+        `await chatgpt.runPlan({ name: "redacted-run-report", input: { result } });`
+    ]),
+    diagnostic("doctor", "Preflight browser bridge, login, upload, download, clipboard, mode, and tool readiness.", [
+        `await chatgpt.doctor({ check: ["bridge", "login", "upload"] });`
+    ]),
+    report("createReport", "Write a durable redacted run report for a command result.", [
+        `await chatgpt.createReport(result, { destDir: "/tmp/reports" });`
+    ]),
+    primitive("session.bootstrap", "Attach to ChatGPT in Chrome and detect login/blocker state.", 30000),
+    primitive("threads.new", "Open a new ChatGPT thread.", 30000),
+    primitive("threads.search", "Search visible ChatGPT history by query.", 30000),
+    primitive("threads.open", "Open a thread by URL, conversation id, title, or search result.", 30000),
+    primitive("messages.compose", "Fill the composer without submitting.", 30000),
+    primitive("messages.submit", "Submit the current composer contents.", 30000),
+    primitive("messages.ask", "Compose, submit, optionally wait, and optionally read.", 120000),
+    primitive("messages.wait", "Wait for the latest assistant response to stabilize.", 120000),
+    primitive("messages.readLatest", "Read the latest message as Markdown, normalized text, blocks, or HTML.", 30000),
+    primitive("messages.waitAndRead", "Wait for completion and read the latest message.", 120000),
+    primitive("files.attach", "Attach absolute local file paths through visible ChatGPT upload controls.", 180000),
+    primitive("files.downloadLatest", "Download the latest visible ChatGPT file affordance.", 120000),
+    primitive("response.copy", "Click Copy response and return clipboard Markdown, with DOM fallback.", 5000),
+    primitive("modes.set", "Select a visible model or effort candidate when unambiguous.", 30000),
+    primitive("tools.select", "Select a visible ChatGPT tool when unambiguous.", 30000)
+];
+export function commandDescriptors() {
+    return descriptors.map(cloneDescriptor);
+}
+export function describeCommand(name) {
+    const descriptor = descriptors.find(item => item.name === name);
+    if (descriptor === undefined)
+        return undefined;
+    return cloneDescriptor(descriptor);
+}
+export function helpText(topic) {
+    if (topic !== undefined) {
+        const descriptor = describeCommand(topic);
+        if (descriptor === undefined)
+            return `No ChatGPT browser-control command is registered as "${topic}".`;
+        return [
+            `${descriptor.name} (${descriptor.layer}, ${descriptor.risk} risk)`,
+            descriptor.summary,
+            descriptor.defaultTimeoutMs === undefined ? undefined : `Default timeout: ${descriptor.defaultTimeoutMs} ms`,
+            Object.keys(descriptor.args).length === 0 ? undefined : `Args: ${Object.entries(descriptor.args).map(([name, description]) => `${name} (${description})`).join(", ")}`,
+            Object.keys(descriptor.defaults).length === 0 ? undefined : `Defaults: ${JSON.stringify(descriptor.defaults)}`,
+            `Retry policy: ${descriptor.retryPolicy}`,
+            descriptor.blockers.length === 0 ? undefined : `Blockers: ${descriptor.blockers.join(", ")}`,
+            descriptor.examples.length === 0 ? undefined : `Example: ${descriptor.examples[0]}`
+        ].filter((line) => line !== undefined).join("\n");
+    }
+    const grouped = groupByLayer(descriptors);
+    return [
+        "ChatGPT browser-control SDK commands",
+        "",
+        ...["workflow", "diagnostic", "report", "primitive"]
+            .flatMap(layer => [
+            `${layer}:`,
+            ...(grouped[layer] ?? []).map(descriptor => `- ${descriptor.name}: ${descriptor.summary}`)
+        ])
+    ].join("\n");
+}
+function workflow(name, summary, examples) {
+    return {
+        name,
+        layer: "workflow",
+        summary,
+        risk: "medium",
+        defaultTimeoutMs: 120000,
+        args: workflowArgs(name),
+        defaults: workflowDefaults(name),
+        retryPolicy: "Return structured CommandResult failures; do not resubmit prompts unless the sequence policy permits unmatched-turn recovery.",
+        blockers: commonBlockers(),
+        examples
+    };
+}
+function diagnostic(name, summary, examples) {
+    return {
+        name,
+        layer: "diagnostic",
+        summary,
+        risk: "low",
+        defaultTimeoutMs: 30000,
+        args: diagnosticArgs(name),
+        defaults: {},
+        retryPolicy: "Return structured readiness checks; retry only after the reported blocker or permission setting changes.",
+        blockers: ["browser_bridge_unavailable", "login_required", "selector_drift"],
+        examples
+    };
+}
+function report(name, summary, examples) {
+    return {
+        name,
+        layer: "report",
+        summary,
+        risk: "low",
+        defaultTimeoutMs: 5000,
+        args: reportArgs(name),
+        defaults: { includeContent: false, maxPreviewChars: 240 },
+        retryPolicy: "Do not retry blindly; preserve redaction defaults and report filesystem errors as CommandResult failures.",
+        blockers: ["permission"],
+        examples
+    };
+}
+function primitive(name, summary, defaultTimeoutMs) {
+    return {
+        name,
+        layer: "primitive",
+        summary,
+        risk: riskForCommand(name),
+        defaultTimeoutMs,
+        args: primitiveArgs(name),
+        defaults: {},
+        retryPolicy: "Return structured CommandResult failures; retry only when the blocker is recoverable and no duplicate prompt will be submitted.",
+        blockers: primitiveBlockers(name),
+        examples: primitiveExamples(name)
+    };
+}
+function workflowArgs(name) {
+    if (name === "find-open-copy-latest")
+        return { query: "history search query" };
+    if (name === "find-open-ask-read")
+        return { query: "history search query", prompt: "message to send" };
+    if (name === "attach-ask-read")
+        return { files: "absolute local file paths", prompt: "message to send" };
+    if (name === "ask-and-download")
+        return { prompt: "message to send", destDir: "download destination directory" };
+    if (name === "two-turn")
+        return { first: "first message", second: "second message" };
+    if (name === "new-ask-read")
+        return { prompt: "message to send" };
+    if (name === "askWithFiles") {
+        return {
+            files: "absolute local file paths to attach before submitting",
+            prompt: "message to send after files are attached",
+            thread: "optional thread selector",
+            existingTab: "true or explicit policy to claim a user-open Chrome tab instead of opening a replacement",
+            mode: "optional visible mode selection, e.g. { effort: \"Thinking\" }",
+            wait: "true or wait options; defaults to true",
+            read: "true or read options such as { format: \"markdown\" }; defaults to Markdown",
+            report: "optional redacted report settings"
+        };
+    }
+    return {
+        prompt: "message to send or workflow-specific input",
+        thread: "optional thread selector",
+        existingTab: "true or explicit policy to claim a user-open Chrome tab instead of opening a replacement",
+        report: "optional redacted report settings"
+    };
+}
+function workflowDefaults(name) {
+    if (name === "copyLatest" || name === "find-open-copy-latest")
+        return { prefer: "clipboard", format: "markdown" };
+    if (name === "runPlan")
+        return {};
+    return { wait: true, read: { format: "markdown" } };
+}
+function diagnosticArgs(name) {
+    if (name === "doctor-upload")
+        return {};
+    return { check: "optional list of readiness checks" };
+}
+function reportArgs(name) {
+    if (name === "redacted-run-report")
+        return { result: "CommandResult to persist" };
+    return { result: "CommandResult to persist", destDir: "optional report directory" };
+}
+function primitiveArgs(name) {
+    if (name === "messages.readLatest")
+        return { role: "assistant or user", format: "markdown, normalized_text, visible_text, html, blocks, or all" };
+    if (name === "response.copy")
+        return { prefer: "clipboard or dom", format: "markdown, normalized_text, visible_text, html, blocks, or all" };
+    if (name.startsWith("threads.search"))
+        return { query: "history search query" };
+    if (name.startsWith("files.attach"))
+        return { paths: "absolute local file paths" };
+    if (name === "modes.set") {
+        return {
+            effort: "visible effort label such as Thinking or Extended",
+            model: "visible model label such as Instant, Pro, or another available model",
+            timeoutMs: "optional timeout for opening and selecting the visible mode menu"
+        };
+    }
+    return {};
+}
+function primitiveExamples(name) {
+    if (name === "modes.set") {
+        return [
+            `await chatgpt.modes.set({ effort: "Thinking" });`,
+            `await chatgpt.askWithFiles({ mode: { effort: "Thinking" }, files: ["/absolute/path.jpg"], prompt: "Describe this image.", wait: true });`
+        ];
+    }
+    if (name === "files.attach") {
+        return [`await chatgpt.files.attach({ paths: ["/absolute/path.jpg"] });`];
+    }
+    return [];
+}
+function primitiveBlockers(name) {
+    if (name.startsWith("files.attach"))
+        return ["browser_bridge_unavailable", "login_required", "permission", "upload_failed"];
+    if (name.startsWith("files.download"))
+        return ["browser_bridge_unavailable", "login_required", "download_unavailable"];
+    if (name.startsWith("modes.") || name.startsWith("tools."))
+        return ["browser_bridge_unavailable", "login_required", "selector_drift"];
+    return commonBlockers();
+}
+function commonBlockers() {
+    return ["browser_bridge_unavailable", "login_required", "captcha", "rate_limit", "selector_drift"];
+}
+function groupByLayer(items) {
+    return items.reduce((grouped, item) => {
+        grouped[item.layer].push(item);
+        return grouped;
+    }, { workflow: [], primitive: [], diagnostic: [], report: [] });
+}
+function cloneDescriptor(descriptor) {
+    return {
+        ...descriptor,
+        args: { ...descriptor.args },
+        defaults: { ...descriptor.defaults },
+        blockers: [...descriptor.blockers],
+        examples: [...descriptor.examples]
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { CommandResult, RuntimeEnv } from "../types.js";
+export type RunReportOptions = {
+    enabled?: boolean;
+    destDir?: string;
+    basename?: string;
+    includeContent?: boolean;
+    maxPreviewChars?: number;
+};
+export type RunReportData = {
+    path: string;
+    bytes: number;
+    includeContent: boolean;
+};
+export declare function createRunReport(env: RuntimeEnv, result: CommandResult<unknown>, options?: RunReportOptions): Promise<CommandResult<RunReportData>>;