codex-chatgpt-control 0.1.0-alpha.1

package/dist/src/runner/types.d.ts

@@ -0,0 +1,264 @@
+import type { AttachedFile, CommandResult, CommandStatus, CopyResponseArgs, DownloadLatestArgs, BootstrapArgs, ReadLatestArgs, ResponseCaptureFidelity, ResponseCaptureSource, ResponseFormat, SequencePlan, SelectToolArgs, SetModeArgs, ThreadTarget, WaitArgs } from "../types.js";
+import type { RunReportOptions } from "../commands/reports.js";
+import type { ChatGPTRunStream } from "./stream.js";
+export type ChatGPTThreadSelector = {
+    type: "new";
+} | {
+    type: "current";
+} | {
+    type: "url";
+    url: string;
+} | {
+    type: "conversationId";
+    conversationId: string;
+} | {
+    type: "conversation_id";
+    conversationId: string;
+} | {
+    type: "search";
+    query: string;
+    select?: "first" | {
+        index: number;
+    } | {
+        title: string;
+    };
+    limit?: number;
+} | {
+    type: "title";
+    title: string;
+};
+export type ChatGPTAttachmentInput = {
+    path: string;
+    description?: string;
+    sensitivity?: "normal" | "sensitive" | "highly_sensitive";
+};
+export type ChatGPTResponseReadOptions = ReadLatestArgs;
+export type ChatGPTVisibleModePreference = SetModeArgs & {
+    required?: boolean;
+    ifUnavailable?: "continue" | "block" | "skip";
+};
+export type ChatGPTVisibleToolPreference = SelectToolArgs & {
+    required?: boolean;
+    ifUnavailable?: "continue" | "block" | "skip";
+};
+export type ChatGPTRunDefaults = {
+    thread?: ChatGPTThreadSelector | ThreadTarget;
+    existingTab?: BootstrapArgs["existingTab"];
+    preferExistingTab?: boolean;
+    mode?: ChatGPTVisibleModePreference;
+    wait?: boolean | WaitArgs;
+    read?: boolean | ReadLatestArgs;
+    report?: boolean | RunReportOptions;
+};
+export type ChatGPTOutputSpec<TOutput = string> = {
+    parse?: "text" | "json";
+    onParseError?: "return_text" | "unsupported" | "error";
+    sample?: TOutput;
+};
+export type ChatGPTBrowserTool = {
+    name: string;
+    command: string;
+    risk?: "low" | "medium" | "high";
+};
+export type ChatGPTGuardrail = {
+    name: string;
+    scope: "input" | "plan" | "step" | "output" | "report";
+};
+export type ChatGPTAgentConfig<TOutput = string> = {
+    name: string;
+    instructions?: string;
+    instructionsMode?: "visible_prefix" | "visible_setup_message" | "metadata_only";
+    defaults?: Partial<ChatGPTRunDefaults>;
+    tools?: ChatGPTBrowserTool[];
+    guardrails?: ChatGPTGuardrail[];
+    output?: ChatGPTOutputSpec<TOutput>;
+    metadata?: Record<string, unknown>;
+};
+export type ChatGPTAgent<TOutput = string> = {
+    readonly kind: "chatgpt_browser_agent";
+    readonly name: string;
+    readonly instructions?: string;
+    readonly instructionsMode: "visible_prefix" | "visible_setup_message" | "metadata_only";
+    readonly defaults: Partial<ChatGPTRunDefaults>;
+    readonly tools: ChatGPTBrowserTool[];
+    readonly guardrails: ChatGPTGuardrail[];
+    readonly output?: ChatGPTOutputSpec<TOutput>;
+    readonly metadata?: Record<string, unknown>;
+};
+export type ChatGPTInputItem = {
+    type: "input_text";
+    text: string;
+    role?: "user";
+} | {
+    type: "input_file";
+    path: string;
+    description?: string;
+} | {
+    type: "visible_instruction";
+    text: string;
+};
+export type ChatGPTRunInput = string | {
+    input: string | ChatGPTInputItem[];
+    thread?: ChatGPTThreadSelector;
+    existingTab?: BootstrapArgs["existingTab"];
+    preferExistingTab?: boolean;
+    attachments?: ChatGPTAttachmentInput[];
+    mode?: ChatGPTVisibleModePreference;
+    tools?: ChatGPTVisibleToolPreference[];
+    response?: ChatGPTResponseReadOptions;
+    download?: DownloadLatestArgs | false;
+    copy?: CopyResponseArgs | false;
+    report?: boolean | RunReportOptions;
+    metadata?: Record<string, unknown>;
+};
+export type ChatGPTThreadRef = {
+    url?: string;
+    conversationId?: string;
+    title?: string;
+};
+export type AttachedFileSummary = Pick<AttachedFile, "path" | "name" | "bytes">;
+export type DownloadedFileSummary = {
+    path: string;
+    suggestedFilename?: string;
+    bytes: number;
+};
+export type ChatGPTRunItem = {
+    type: "thread.opened";
+    thread: ChatGPTThreadRef;
+} | {
+    type: "mode.selected";
+    requested?: string;
+    selected?: string;
+    candidates?: string[];
+} | {
+    type: "tool.selected";
+    requested: string;
+    selected?: string;
+    candidates?: string[];
+} | {
+    type: "file.attached";
+    file: AttachedFileSummary;
+} | {
+    type: "message.submitted";
+    role: "user";
+    preview: string;
+    redacted: boolean;
+} | {
+    type: "message.completed";
+    role: "assistant";
+    output_text?: string;
+    format: ResponseFormat;
+    source?: ResponseCaptureSource;
+    fidelity?: ResponseCaptureFidelity;
+} | {
+    type: "file.downloaded";
+    file: DownloadedFileSummary;
+} | {
+    type: "approval.required";
+    interruption: ChatGPTInterruption;
+} | {
+    type: "run.blocked";
+    blocker: ChatGPTCommandBlocker;
+};
+export type RemediationStep = {
+    label: string;
+    instruction: string;
+    userActionRequired: boolean;
+};
+export type VisibleCandidate = {
+    label: string;
+    role?: string;
+};
+export type ChatGPTCommandBlocker = NonNullable<CommandResult["blocker"]> & {
+    code?: string;
+    fieldPath?: string;
+    remediation?: RemediationStep[];
+    candidates?: VisibleCandidate[];
+    resumable?: boolean;
+};
+export type ChatGPTInterruption = {
+    id: string;
+    type: "approval_required" | "permission_required" | "login_required" | "selector_drift" | "rate_limit" | "captcha" | "unsupported" | "timeout";
+    status: CommandStatus;
+    blocker?: ChatGPTCommandBlocker;
+    command?: string;
+    fieldPath?: string;
+    message: string;
+    fix?: {
+        summary: string;
+        steps: string[];
+    };
+    resume: {
+        supported: boolean;
+        stateId?: string;
+        reason?: string;
+    };
+};
+export type ChatGPTInterruptionDecision = {
+    id: string;
+    decision: "approve";
+    confirm: ChatGPTConfirmation;
+} | {
+    id: string;
+    decision: "reject";
+    message?: string;
+};
+export type ChatGPTConfirmation = {
+    targetKind: "file_upload" | "download" | "thread" | "shared_link" | "third_party_app" | "account_setting" | "workspace_setting" | "external_action" | "quota_consuming_tool";
+    targetDisplayName: string;
+    action: string;
+    risks?: string[];
+    understood: true;
+};
+export type ChatGPTRunState = {
+    id: string;
+    resumable: boolean;
+    thread?: ChatGPTThreadRef;
+    nextStepId?: string;
+};
+export type ChatGPTRunData<TOutput = string> = {
+    finalOutput?: TOutput;
+    outputText: string;
+    thread?: ChatGPTThreadRef;
+    downloads?: DownloadedFileSummary[];
+    reportPath?: string;
+};
+export type ChatGPTRunResult<TOutput = string> = CommandResult<ChatGPTRunData<TOutput>> & {
+    finalOutput?: TOutput;
+    output_text: string;
+    output: ChatGPTRunItem[];
+    newItems: ChatGPTRunItem[];
+    interruptions: ChatGPTInterruption[];
+    state: ChatGPTRunState;
+    activeAgentName: string;
+    lastAgentName: string;
+};
+export type ChatGPTRunner = {
+    run<TOutput = string>(agent: ChatGPTAgent<TOutput>, input: ChatGPTRunInput, options: {
+        stream: true;
+    }): ChatGPTRunStream<TOutput>;
+    run<TOutput = string>(agent: ChatGPTAgent<TOutput>, input: ChatGPTRunInput, options?: {
+        stream?: false;
+    }): Promise<ChatGPTRunResult<TOutput>>;
+    plan<TOutput = string>(agent: ChatGPTAgent<TOutput>, input: ChatGPTRunInput): SequencePlan;
+};
+export type ChatGPTResponse = {
+    id: string;
+    object: "chatgpt.browser.response";
+    created_at: number;
+    status: CommandStatus;
+    output_text: string;
+    output: ChatGPTRunItem[];
+    browser_control: {
+        visibleUi: true;
+        resultStatus: CommandStatus;
+        thread?: ChatGPTThreadRef;
+        reportPath?: string;
+        unsupported?: UnsupportedField[];
+    };
+};
+export type UnsupportedField = {
+    path: string;
+    reason: string;
+    alternative?: string;
+};

package/dist/src/runner/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/safety/blockers.d.ts

@@ -0,0 +1,7 @@
+import type { BlockerKind } from "../types.js";
+export type ClassifiedBlocker = {
+    kind: BlockerKind;
+    message: string;
+    visibleText?: string;
+};
+export declare function classifyVisibleText(text: string): ClassifiedBlocker | undefined;

package/dist/src/safety/blockers.js

@@ -0,0 +1,60 @@
+import { compactVisibleText } from "./redaction.js";
+const RULES = [
+    {
+        kind: "login_required",
+        message: "ChatGPT requires the user to sign in before continuing.",
+        patterns: [/\blog\s?in\b/i, /\bsign\s?in\b/i, /\bwelcome back\b/i]
+    },
+    {
+        kind: "captcha",
+        message: "ChatGPT is showing a captcha or suspicious-activity challenge.",
+        patterns: [/\bcaptcha\b/i, /verify (?:you are|that you are) human/i, /suspicious activity/i]
+    },
+    {
+        kind: "rate_limit",
+        message: "ChatGPT is rate limited or out of usage for this account.",
+        patterns: [/usage limit/i, /rate limit/i, /try again later/i, /too many requests/i]
+    },
+    {
+        kind: "permission",
+        message: "File upload permission is required. Ask the user to enable both: Codex Settings > Computer Use > Chrome > Permissions > Uploads, and Chrome chrome://extensions > Codex extension > Details > Allow access to file URLs.",
+        patterns: [/allow access to file urls/i, /file upload permission/i, /fileChooser\.setFiles/i]
+    },
+    {
+        kind: "permission",
+        message: "A browser or ChatGPT permission is required before continuing.",
+        patterns: [/permission denied/i, /browser blocked/i]
+    },
+    {
+        kind: "upload_failed",
+        message: "ChatGPT reported a file upload failure.",
+        patterns: [/upload failed/i, /could(?: not|n't) upload/i, /unsupported file/i, /file is too large/i]
+    },
+    {
+        kind: "download_unavailable",
+        message: "No downloadable file or download control is visible.",
+        patterns: [/download unavailable/i, /no download/i]
+    },
+    {
+        kind: "not_found",
+        message: "The requested ChatGPT conversation or page was not found.",
+        patterns: [/conversation not found/i, /404/i, /page not found/i]
+    }
+];
+export function classifyVisibleText(text) {
+    const visibleText = compactVisibleText(text);
+    const lowerable = visibleText.length > 0 ? visibleText : text;
+    for (const rule of RULES) {
+        if (rule.patterns.some(pattern => pattern.test(lowerable))) {
+            return { kind: rule.kind, message: rule.message, visibleText };
+        }
+    }
+    if (/\b(confirm|continue|cancel|dismiss)\b/i.test(lowerable) && /\bdialog\b|\bmodal\b/i.test(lowerable)) {
+        return {
+            kind: "modal",
+            message: "ChatGPT is showing a modal dialog that may require user action.",
+            visibleText
+        };
+    }
+    return undefined;
+}

package/dist/src/safety/redaction.d.ts

@@ -0,0 +1,2 @@
+export declare function redactSensitiveText(text: string): string;
+export declare function compactVisibleText(text: string, maxLength?: number): string;

package/dist/src/safety/redaction.js

@@ -0,0 +1,18 @@
+const EMAIL_RE = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+const PHONE_RE = /\b(?:\+?1[-.\s]?)?(?:\(?\d{3}\)?[-.\s]?)\d{3}[-.\s]?\d{4}\b/g;
+const TOKEN_RE = /\b[A-Za-z0-9_-]{32,}\b/g;
+const PATH_RE = /(?:\/Users\/|\/home\/|\/example\/user\/)[^\s"'<>]+/g;
+export function redactSensitiveText(text) {
+    return text
+        .replace(EMAIL_RE, "[redacted-email]")
+        .replace(PHONE_RE, "[redacted-phone]")
+        .replace(PATH_RE, "[redacted-path]")
+        .replace(TOKEN_RE, "[redacted-token]");
+}
+export function compactVisibleText(text, maxLength = 1000) {
+    const compacted = redactSensitiveText(text.replace(/\s+/g, " ").trim());
+    if (compacted.length <= maxLength) {
+        return compacted;
+    }
+    return `${compacted.slice(0, maxLength - 1)}...`;
+}

package/dist/src/safety/report-redaction.d.ts

@@ -0,0 +1,8 @@
+export type ReportRedactionOptions = {
+    includeContent?: boolean;
+    maxPreviewChars?: number;
+    maxDepth?: number;
+    maxArrayItems?: number;
+    maxObjectEntries?: number;
+};
+export declare function redactReportValue(value: unknown, options?: ReportRedactionOptions): unknown;

package/dist/src/safety/report-redaction.js

@@ -0,0 +1,74 @@
+import { compactVisibleText, redactSensitiveText } from "./redaction.js";
+const DEFAULT_MAX_PREVIEW_CHARS = 240;
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_ARRAY_ITEMS = 40;
+const DEFAULT_MAX_OBJECT_ENTRIES = 80;
+export function redactReportValue(value, options = {}) {
+    return redactValue(value, normalizeOptions(options), 0, new WeakSet(), undefined);
+}
+function redactValue(value, options, depth, seen, key) {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value === "string") {
+        if (!options.includeContent && key !== undefined && isSafeControlStringKey(key)) {
+            return value;
+        }
+        if (!options.includeContent)
+            return `[redacted:${value.length} chars]`;
+        return compactVisibleText(redactSensitiveText(value), options.maxPreviewChars);
+    }
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value !== "object")
+        return redactSensitiveText(String(value));
+    if (seen.has(value))
+        return "[redacted:cycle]";
+    if (depth >= options.maxDepth)
+        return "[redacted:max-depth]";
+    if (!options.includeContent && key !== undefined && isHeavyContentKey(key)) {
+        return summarizeHeavyValue(value);
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const items = value.slice(0, options.maxArrayItems)
+                .map(item => redactValue(item, options, depth + 1, seen, key));
+            if (value.length > options.maxArrayItems) {
+                items.push(`[redacted:${value.length - options.maxArrayItems} more items]`);
+            }
+            return items;
+        }
+        const entries = Object.entries(value);
+        const kept = entries.slice(0, options.maxObjectEntries).map(([childKey, child]) => [
+            childKey,
+            redactValue(child, options, depth + 1, seen, childKey)
+        ]);
+        if (entries.length > options.maxObjectEntries) {
+            kept.push(["__redactedMoreEntries", entries.length - options.maxObjectEntries]);
+        }
+        return Object.fromEntries(kept);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function normalizeOptions(options) {
+    return {
+        includeContent: options.includeContent === true,
+        maxPreviewChars: options.maxPreviewChars ?? DEFAULT_MAX_PREVIEW_CHARS,
+        maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH,
+        maxArrayItems: options.maxArrayItems ?? DEFAULT_MAX_ARRAY_ITEMS,
+        maxObjectEntries: options.maxObjectEntries ?? DEFAULT_MAX_OBJECT_ENTRIES
+    };
+}
+function isHeavyContentKey(key) {
+    return /^(text|markdown|html|visibleText|normalizedText|responseText|output_text|outputText|finalOutput|prompt|blocks|tables|codeBlocks|dataPreview)$/i.test(key);
+}
+function summarizeHeavyValue(value) {
+    if (Array.isArray(value))
+        return `[redacted-array:${value.length} items]`;
+    return "[redacted-object]";
+}
+function isSafeControlStringKey(key) {
+    return /^(schemaVersion|status|startedAt|endedAt|createdAt|timestamp|requiredFailures)$/i.test(key);
+}

package/dist/src/safety/risk.d.ts

@@ -0,0 +1,26 @@
+export type RiskLevel = "low" | "medium" | "high";
+export declare const commandRisk: {
+    readonly "session.bootstrap": "low";
+    readonly "threads.search": "medium";
+    readonly "threads.open": "medium";
+    readonly "threads.new": "low";
+    readonly "messages.compose": "low";
+    readonly "messages.submit": "medium";
+    readonly "messages.ask": "medium";
+    readonly "messages.wait": "low";
+    readonly "messages.readLatest": "medium";
+    readonly "messages.waitAndRead": "medium";
+    readonly "files.attach": "medium";
+    readonly "files.downloadLatest": "medium";
+    readonly "response.copy": "medium";
+    readonly "modes.set": "medium";
+    readonly "tools.select": "medium";
+    readonly "threads.delete": "high";
+    readonly "threads.archive": "high";
+    readonly "threads.share": "high";
+    readonly "settings.change": "high";
+    readonly "apps.connect": "high";
+};
+export type KnownRiskCommand = keyof typeof commandRisk;
+export declare function riskForCommand(command: string): RiskLevel;
+export declare function isHighRiskCommand(command: string): boolean;

package/dist/src/safety/risk.js

@@ -0,0 +1,28 @@
+export const commandRisk = {
+    "session.bootstrap": "low",
+    "threads.search": "medium",
+    "threads.open": "medium",
+    "threads.new": "low",
+    "messages.compose": "low",
+    "messages.submit": "medium",
+    "messages.ask": "medium",
+    "messages.wait": "low",
+    "messages.readLatest": "medium",
+    "messages.waitAndRead": "medium",
+    "files.attach": "medium",
+    "files.downloadLatest": "medium",
+    "response.copy": "medium",
+    "modes.set": "medium",
+    "tools.select": "medium",
+    "threads.delete": "high",
+    "threads.archive": "high",
+    "threads.share": "high",
+    "settings.change": "high",
+    "apps.connect": "high"
+};
+export function riskForCommand(command) {
+    return commandRisk[command] ?? "high";
+}
+export function isHighRiskCommand(command) {
+    return riskForCommand(command) === "high";
+}

package/dist/src/scripts/backend-server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/scripts/backend-server.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runBackendStdioServer } from "../backend/stdio-server.js";
+await runBackendStdioServer({
+    input: process.stdin,
+    output: process.stdout,
+    error: process.stderr
+});

package/dist/src/scripts/check-parity-suite.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/check-parity-suite.js

@@ -0,0 +1,10 @@
+import { validateParitySuite } from "../testing/parity-suite.js";
+const report = validateParitySuite();
+console.log([
+    `Validated polyglot parity suite:`,
+    `- evidence mode: ${report.evidenceMode}`,
+    `- ${report.surfaceCount} surfaces`,
+    `- ${report.fixtureCount} contract fixtures`,
+    `- ${report.commandCount} backend commands`,
+    `- ${report.gateCount} deterministic gates`
+].join("\n"));

package/dist/src/scripts/continue-thread.d.ts

@@ -0,0 +1,27 @@
+import { type ChatGPTClient, type WorkflowThread } from "../client.js";
+import type { CommandResult, ExistingTabPolicy, ResponseFormat } from "../types.js";
+export declare const CONTINUE_THREAD_USAGE: string;
+export type ContinueThreadOptions = {
+    target?: string;
+    existing?: ExistingTabPolicy;
+    prompt?: string;
+    format: ResponseFormat;
+    maxChars?: number;
+    timeoutMs?: number;
+    stableMs?: number;
+};
+export type ContinueThreadClient = Pick<ChatGPTClient, "askInThread" | "openThread" | "readLatest" | "session">;
+export type ContinueThreadSelector = Exclude<WorkflowThread, {
+    type: "new";
+}>;
+export declare class ContinueThreadUsageError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export declare function parseContinueThreadCliArgs(argv: string[], env?: Record<string, string | undefined>): ContinueThreadOptions;
+export declare function threadSelectorFromTarget(target: string, args?: {
+    limit?: number;
+}): ContinueThreadSelector;
+export declare function runContinueThread(client: ContinueThreadClient, options: ContinueThreadOptions): Promise<CommandResult<unknown>>;
+export declare function renderContinueThreadOutput(result: CommandResult<unknown>): Record<string, unknown>;
+export declare function main(argv?: string[], env?: Record<string, string | undefined>): Promise<number>;