codex-chatgpt-control 0.1.0-alpha.1

package/dist/src/commands/reports.js

@@ -0,0 +1,47 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resultError, resultOk } from "../errors.js";
+import { redactReportValue } from "../safety/report-redaction.js";
+import { contextFromPage } from "./context.js";
+export async function createRunReport(env, result, options = {}) {
+    try {
+        const destDir = options.destDir ?? "reports/runs";
+        await mkdir(destDir, { recursive: true });
+        const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+        const safeBase = sanitizeBasename(options.basename ?? "chatgpt-run-report");
+        const path = join(destDir, `${stamp}-${safeBase}.json`);
+        const includeContent = options.includeContent === true;
+        const summary = redactReportValue({
+            ok: result.ok,
+            status: result.status,
+            warnings: result.warnings,
+            blocker: result.blocker,
+            error: result.error,
+            context: result.context,
+            reportPath: result.reportPath
+        }, options);
+        const report = {
+            schemaVersion: 1,
+            createdAt: new Date().toISOString(),
+            includeContent,
+            summary,
+            steps: result.steps?.map(step => ({
+                ...step,
+                dataPreview: redactReportValue(step.dataPreview, options)
+            })),
+            data: redactReportValue(result.data, options)
+        };
+        await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+        const saved = await stat(path);
+        return resultOk({ path, bytes: saved.size, includeContent }, await contextFromPage(env.page));
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(env.page));
+    }
+}
+function sanitizeBasename(name) {
+    return name.toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        || "chatgpt-run-report";
+}

package/dist/src/commands/response-actions.d.ts

@@ -0,0 +1,2 @@
+import type { CommandResult, CopiedResponse, CopyResponseArgs, RuntimeEnv } from "../types.js";
+export declare function copyResponse(env: RuntimeEnv, args?: CopyResponseArgs): Promise<CommandResult<CopiedResponse>>;

package/dist/src/commands/response-actions.js

@@ -0,0 +1,141 @@
+import { readSystemClipboard, waitForClipboardChange } from "../browser/clipboard.js";
+import { formatClipboardMarkdown, normalizeResponseFormat } from "../dom/message-format.js";
+import { resultError, resultOk } from "../errors.js";
+import { readLatestMessage, readMessages } from "../dom/messages.js";
+import { copyResponseButtons } from "../dom/selectors.js";
+import { contextFromPage } from "./context.js";
+import { withCommandOutputText } from "./output.js";
+import { bootstrap } from "./session.js";
+export async function copyResponse(env, args = {}) {
+    const boot = await ensurePage(env);
+    if (!boot.ok) {
+        return boot;
+    }
+    const page = env.page;
+    try {
+        if (args.prefer !== "dom") {
+            const before = await readClipboard(env);
+            const buttons = copyResponseButtons(page);
+            const target = args.which === undefined || args.which === "latest"
+                ? buttons.last?.() ?? buttons
+                : buttons.nth?.(args.which.assistantIndex) ?? buttons;
+            await target.click?.();
+            const copied = await waitForClipboard(env, before, args.timeoutMs ?? 3000);
+            if (copied !== undefined) {
+                const requestedFormat = normalizeResponseFormat(args.format);
+                if (requestedFormat === "html" || requestedFormat === "blocks" || requestedFormat === "all") {
+                    const latest = await readSelectedAssistantMessage(page, args.which, requestedFormat);
+                    if (latest !== undefined) {
+                        const fallbackReason = `Clipboard copy succeeded, but ${formatLabel(requestedFormat)} requires DOM extraction.`;
+                        const data = copiedResponseFromExtracted(latest, "dom", fallbackReason);
+                        data.markdown = formatClipboardMarkdown(copied).markdown ?? copied;
+                        data.warnings = [...(data.warnings ?? []), fallbackReason];
+                        return withCommandOutputText(resultOk(data, await contextFromPage(page), data.warnings));
+                    }
+                    const warning = `Clipboard copy succeeded, but ${formatLabel(requestedFormat)} requires DOM extraction and no assistant DOM message was available; returned clipboard Markdown instead.`;
+                    const data = {
+                        ...formatClipboardMarkdown(copied, undefined, "markdown"),
+                        source: "clipboard",
+                        fallbackReason: warning,
+                        warnings: [warning]
+                    };
+                    return withCommandOutputText(resultOk(data, await contextFromPage(page), [warning]));
+                }
+                const metadata = await readSelectedAssistantMessage(page, args.which, "markdown").catch(() => undefined);
+                const data = {
+                    ...formatClipboardMarkdown(copied, undefined, args.format),
+                    source: "clipboard"
+                };
+                mergeResponseMetadata(data, metadata);
+                return withCommandOutputText(resultOk(data, await contextFromPage(page)));
+            }
+        }
+        const latest = await readSelectedAssistantMessage(page, args.which, args.format ?? "markdown");
+        if (latest !== undefined) {
+            const fallbackReason = args.prefer === "dom"
+                ? `Returned DOM-derived ${formatLabel(latest.format)} because clipboard copy was not requested.`
+                : "System clipboard did not change; returned DOM-derived response content.";
+            const data = copiedResponseFromExtracted(latest, "dom", fallbackReason);
+            return withCommandOutputText(resultOk(data, await contextFromPage(page), data.warnings ?? [fallbackReason]));
+        }
+        return {
+            ok: false,
+            status: "not_found",
+            warnings: [],
+            blocker: {
+                kind: "not_found",
+                message: "No assistant response was available to copy."
+            },
+            context: await contextFromPage(page)
+        };
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)), await contextFromPage(page));
+    }
+}
+function readClipboard(env) {
+    return env.clipboard?.read() ?? readSystemClipboard();
+}
+function waitForClipboard(env, before, timeoutMs) {
+    return env.clipboard?.waitForChange(before, timeoutMs) ?? waitForClipboardChange(before, timeoutMs);
+}
+async function readSelectedAssistantMessage(page, which, format = "markdown") {
+    if (which === undefined || which === "latest") {
+        return readLatestMessage(page, "assistant", format);
+    }
+    const messages = await readMessages(page, { role: "assistant", format });
+    return messages.at(which.assistantIndex);
+}
+function formatLabel(format) {
+    return format === "markdown" ? "Markdown" : format.replaceAll("_", " ");
+}
+function copiedResponseFromExtracted(latest, source, fallbackReason) {
+    const data = {
+        text: latest.text,
+        format: latest.format,
+        source
+    };
+    if (latest.fidelity !== undefined)
+        data.fidelity = latest.fidelity;
+    if (latest.warnings !== undefined || fallbackReason !== undefined) {
+        data.warnings = [...(latest.warnings ?? []), ...(fallbackReason === undefined ? [] : [fallbackReason])];
+    }
+    if (fallbackReason !== undefined)
+        data.fallbackReason = fallbackReason;
+    mergeResponseMetadata(data, latest);
+    return data;
+}
+function mergeResponseMetadata(data, latest) {
+    if (latest === undefined)
+        return;
+    if (latest.markdown !== undefined && data.markdown === undefined)
+        data.markdown = latest.markdown;
+    if (latest.visibleText !== undefined)
+        data.visibleText = latest.visibleText;
+    if (latest.normalizedText !== undefined)
+        data.normalizedText = latest.normalizedText;
+    if (latest.html !== undefined)
+        data.html = latest.html;
+    if (latest.blocks !== undefined)
+        data.blocks = latest.blocks;
+    if (latest.citations !== undefined)
+        data.citations = latest.citations;
+    if (latest.codeBlocks !== undefined)
+        data.codeBlocks = latest.codeBlocks;
+    if (latest.tables !== undefined)
+        data.tables = latest.tables;
+    if (latest.branch !== undefined)
+        data.branch = latest.branch;
+    if (latest.actions !== undefined)
+        data.actions = latest.actions;
+    if (latest.thoughtDurationText !== undefined)
+        data.thoughtDurationText = latest.thoughtDurationText;
+    if (latest.sourcesAvailable !== undefined)
+        data.sourcesAvailable = latest.sourcesAvailable;
+}
+async function ensurePage(env) {
+    if (env.page !== undefined) {
+        return resultOk({}, await contextFromPage(env.page));
+    }
+    return bootstrap(env, { preferExistingTab: true });
+}

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

@@ -0,0 +1,9 @@
+import type { CommandResult, RuntimeEnv, SequencePlan, SequencePolicy, SequenceStep } from "../types.js";
+export type SequenceExecutor = (step: SequenceStep, env: RuntimeEnv, previousResults: Map<string, CommandResult<unknown>>, policy: SequencePolicy) => Promise<CommandResult<unknown>>;
+export declare const defaultSequencePolicy: SequencePolicy;
+export declare function runSequence(plan: SequencePlan, env?: RuntimeEnv): Promise<CommandResult<unknown>>;
+export declare function runSequenceWithExecutor(plan: SequencePlan, executor: SequenceExecutor, env?: RuntimeEnv): Promise<CommandResult<unknown>>;
+export declare function executeStep(step: SequenceStep, env: RuntimeEnv, previousResults: Map<string, CommandResult<unknown>>): Promise<CommandResult<unknown>>;
+export declare function normalizePolicy(policy: Partial<SequencePolicy> | undefined): SequencePolicy;
+export declare function resolveStepArgs(step: SequenceStep, previousResults: Map<string, CommandResult<unknown>>, input?: Record<string, unknown>): SequenceStep;
+export declare function resolveVariableReference(reference: string, previousResults: Map<string, CommandResult<unknown>>, input?: Record<string, unknown>): unknown;

package/dist/src/commands/sequence.js

@@ -0,0 +1,228 @@
+import { attachFiles, downloadLatestFile } from "./files.js";
+import { askMessage, composeMessage, readLatest, submitMessage, waitAndRead, waitForMessage } from "./messages.js";
+import { copyResponse } from "./response-actions.js";
+import { bootstrap } from "./session.js";
+import { newThread, openThread, searchThreads } from "./threads.js";
+import { setMode, selectTool } from "./modes.js";
+import { withCommandOutputText } from "./output.js";
+export const defaultSequencePolicy = {
+    stopOnError: true,
+    returnPartial: true,
+    defaultTimeoutMs: 120000,
+    screenshotOnBlocker: true,
+    allowPromptResubmit: "only_if_no_matching_user_turn"
+};
+export async function runSequence(plan, env = {}) {
+    return runSequenceWithExecutor(plan, executeStep, env);
+}
+export async function runSequenceWithExecutor(plan, executor, env = {}) {
+    const policy = normalizePolicy(plan.policy);
+    const stepResults = [];
+    const values = new Map();
+    const input = plan.input ?? {};
+    for (const step of plan.steps) {
+        const startedAt = new Date().toISOString();
+        const resolvedStep = resolveStepArgs(step, values, input);
+        const result = await executor(resolvedStep, env, values, policy);
+        values.set(step.id, result);
+        stepResults.push(toStepResult(step, result, startedAt));
+        if (!result.ok && policy.stopOnError) {
+            return sequenceFailure(result, values, stepResults, policy);
+        }
+    }
+    const lastStep = plan.steps.at(-1);
+    const finalResult = lastStep === undefined ? okSequenceResult(values, stepResults) : values.get(lastStep.id);
+    if (finalResult === undefined) {
+        return okSequenceResult(values, stepResults);
+    }
+    return withCommandOutputText({ ...finalResult, steps: stepResults });
+}
+export async function executeStep(step, env, previousResults) {
+    switch (step.command) {
+        case "session.bootstrap":
+            return bootstrap(env, step.args);
+        case "threads.search":
+            return searchThreads(env, step.args);
+        case "threads.open":
+            return openThread(env, step.args, previousResults);
+        case "threads.new":
+            return newThread(env, step.args);
+        case "messages.compose":
+            return composeMessage(env, step.args);
+        case "messages.submit":
+            return submitMessage(env, step.args);
+        case "messages.ask":
+            return askMessage(env, step.args);
+        case "messages.wait":
+            return waitForMessage(env, step.args);
+        case "messages.readLatest":
+            return readLatest(env, step.args);
+        case "messages.waitAndRead":
+            return waitAndRead(env, step.args);
+        case "files.attach":
+            return attachFiles(env, step.args);
+        case "files.downloadLatest":
+            return downloadLatestFile(env, step.args);
+        case "response.copy":
+            return copyResponse(env, step.args);
+        case "modes.set":
+            return setMode(env, step.args);
+        case "tools.select":
+            return selectTool(env, step.args);
+    }
+}
+export function normalizePolicy(policy) {
+    return { ...defaultSequencePolicy, ...(policy ?? {}) };
+}
+export function resolveStepArgs(step, previousResults, input = {}) {
+    if (!("args" in step) || step.args === undefined) {
+        return step;
+    }
+    return {
+        ...step,
+        args: resolveValue(step.args, previousResults, input)
+    };
+}
+export function resolveVariableReference(reference, previousResults, input = {}) {
+    const match = /^\$\{([^}]+)\}$/.exec(reference);
+    if (match === null) {
+        return reference;
+    }
+    const path = match[1];
+    if (path === undefined || path.length === 0) {
+        throw new Error("Empty variable reference is not allowed.");
+    }
+    if (path.includes("__proto__") || path.includes("prototype") || path.includes("constructor")) {
+        throw new Error(`Unsafe variable reference rejected: ${path}`);
+    }
+    const [root, ...segments] = tokenizePath(path);
+    let current;
+    if (root === "input") {
+        current = input;
+    }
+    else if (root !== undefined && previousResults.has(root)) {
+        current = previousResults.get(root);
+    }
+    else {
+        throw new Error(`Unknown variable root: ${root ?? ""}`);
+    }
+    for (const segment of segments) {
+        current = readPathSegment(current, segment);
+    }
+    return current;
+}
+function resolveValue(value, previousResults, input) {
+    if (typeof value === "string") {
+        return resolveVariableReference(value, previousResults, input);
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => resolveValue(item, previousResults, input));
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, resolveValue(child, previousResults, input)]));
+    }
+    return value;
+}
+function tokenizePath(path) {
+    const segments = [];
+    for (const part of path.split(".")) {
+        const head = /^([A-Za-z_][A-Za-z0-9_]*)/.exec(part)?.[1];
+        if (head === undefined) {
+            throw new Error(`Invalid variable path segment: ${part}`);
+        }
+        segments.push(head);
+        for (const indexMatch of part.matchAll(/\[(\d+)\]/g)) {
+            segments.push(indexMatch[1]);
+        }
+        const consumed = `${head}${Array.from(part.matchAll(/\[(\d+)\]/g)).map(match => `[${match[1]}]`).join("")}`;
+        if (consumed !== part) {
+            throw new Error(`Invalid variable path segment: ${part}`);
+        }
+    }
+    return segments;
+}
+function readPathSegment(value, segment) {
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        const index = Number(segment);
+        if (!Number.isInteger(index)) {
+            throw new Error(`Array segment must be numeric: ${segment}`);
+        }
+        return value[index];
+    }
+    if (typeof value === "object") {
+        return value[segment];
+    }
+    return undefined;
+}
+function toStepResult(step, result, startedAt) {
+    const stepResult = {
+        id: step.id,
+        command: step.command,
+        status: result.status,
+        ok: result.ok,
+        startedAt,
+        endedAt: new Date().toISOString(),
+        warnings: result.warnings
+    };
+    const dataPreview = previewData(result.data);
+    if (dataPreview !== undefined) {
+        stepResult.dataPreview = dataPreview;
+    }
+    return stepResult;
+}
+function previewData(data) {
+    if (data === undefined) {
+        return undefined;
+    }
+    if (typeof data === "string") {
+        return data.length > 120 ? `${data.slice(0, 119)}...` : data;
+    }
+    if (Array.isArray(data)) {
+        return { type: "array", length: data.length };
+    }
+    if (typeof data === "object" && data !== null) {
+        return Object.fromEntries(Object.entries(data).map(([key, value]) => {
+            if (/text|prompt|response/i.test(key) && typeof value === "string") {
+                return [key, value.length > 120 ? `${value.slice(0, 119)}...` : value];
+            }
+            return [key, value];
+        }));
+    }
+    return data;
+}
+function sequenceFailure(result, values, stepResults, policy) {
+    const failure = {
+        ok: false,
+        status: policy.returnPartial ? "partial" : result.status,
+        data: collectSequenceData(values),
+        warnings: collectWarnings(stepResults, result.warnings),
+        context: result.context,
+        steps: stepResults
+    };
+    if (result.error !== undefined) {
+        failure.error = result.error;
+    }
+    if (result.blocker !== undefined) {
+        failure.blocker = result.blocker;
+    }
+    return withCommandOutputText(failure);
+}
+function okSequenceResult(values, stepResults) {
+    return withCommandOutputText({
+        ok: true,
+        status: "ok",
+        data: collectSequenceData(values),
+        warnings: collectWarnings(stepResults),
+        context: { timestamp: new Date().toISOString() },
+        steps: stepResults
+    });
+}
+function collectSequenceData(values) {
+    return Object.fromEntries(Array.from(values.entries()).map(([id, result]) => [id, result.data]));
+}
+function collectWarnings(stepResults, extra = []) {
+    return [...stepResults.flatMap(step => step.warnings), ...extra];
+}

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

@@ -0,0 +1,2 @@
+import type { BootstrapArgs, BootstrapData, CommandResult, RuntimeEnv } from "../types.js";
+export declare function bootstrap(env: RuntimeEnv, args?: BootstrapArgs): Promise<CommandResult<BootstrapData>>;

package/dist/src/commands/session.js

@@ -0,0 +1,25 @@
+import { attachChatGPTBrowser } from "../browser/attach.js";
+import { readPageState } from "../browser/page-state.js";
+import { resultError, resultOk } from "../errors.js";
+import { contextFromPage } from "./context.js";
+export async function bootstrap(env, args = {}) {
+    try {
+        const attached = await attachChatGPTBrowser(env, args);
+        env.browser = attached.browser;
+        env.page = attached.page;
+        const state = await readPageState(attached.page);
+        const data = {
+            browserName: attached.browserName,
+            tabId: attached.tabId ?? "unknown",
+            url: state.url,
+            loggedIn: state.signedIn
+        };
+        const context = attached.tabId === undefined
+            ? { browserName: attached.browserName }
+            : { browserName: attached.browserName, tabId: attached.tabId };
+        return resultOk(data, await contextFromPage(attached.page, context));
+    }
+    catch (error) {
+        return resultError(error instanceof Error ? error : new Error(String(error)));
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { CommandResult, NewThreadArgs, OpenThreadArgs, OpenThreadData, RuntimeEnv, SearchThreadsArgs, SearchThreadsData, ThreadSearchResult } from "../types.js";
+export declare function extractThreadSearchResultsFromHtml(html: string): ThreadSearchResult[];
+export declare function searchThreads(env: RuntimeEnv, args: SearchThreadsArgs): Promise<CommandResult<SearchThreadsData>>;
+export declare function newThread(env: RuntimeEnv, args?: NewThreadArgs): Promise<CommandResult<OpenThreadData>>;
+export declare function openThread(env: RuntimeEnv, args: OpenThreadArgs, previousResults?: Map<string, CommandResult<unknown>>): Promise<CommandResult<OpenThreadData>>;
+export declare function selectSearchResult(results: ThreadSearchResult[], select?: OpenThreadArgs["select"]): ThreadSearchResult | undefined;